trunk/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 Section
 761 State management
 762 \end_layout
 763
 764 \begin_layout Standard
 765 States are key/value pairs associated with a time range.
 766  Keys can be (and generally are) duplicated as long as they do not apply
 767  to overlapping ranges.
 768 \end_layout
 769
 770 \begin_layout Standard
 771 Keys are character strings.
 772  They are organized in a filesystem-like hierarchy.
 773 \end_layout
 774
 775 \begin_layout Standard
 776 Each key/value pair is associated either to a specific trace or to the traceset.
 777 \end_layout
 778
 779 \begin_layout Standard
 780 State can persist between runs of the program.
 781  This is useful both to reduce pre-calculation times when re-opening a trace,
 782  and also to keep general parameters like bookmarks.
 783 \end_layout
 784
 785 \begin_layout Standard
 786 It is possible to assign a state to the time range -infinity..infinity to
 787  indicate that it is global to the trace.
 788 \end_layout
 789
 790 \begin_layout Standard
 791 Values may be of various types:
 792 \end_layout
 793
 794 \begin_layout Itemize
 795 string
 796 \end_layout
 797
 798 \begin_layout Itemize
 799 uint32
 800 \end_layout
 801
 802 \begin_layout Itemize
 803 int32
 804 \end_layout
 805
 806 \begin_layout Itemize
 807 uint64
 808 \end_layout
 809
 810 \begin_layout Itemize
 811 int64
 812 \end_layout
 813
 814 \begin_layout Itemize
 815 blob (binary block of arbitrary length)
 816 \end_layout
 817
 818 \begin_layout Itemize
 819 float32
 820 \end_layout
 821
 822 \begin_layout Itemize
 823 float64
 824 \end_layout
 825
 826 \begin_layout Itemize
 827 others?
 828 \end_layout
 829
 830 \begin_layout Subsection
 831 Methods of the State Accessing API
 832 \end_layout
 833
 834 \begin_layout Itemize
 835 struct state_value *state_get_value_at_time(char *key, struct trace_time
 836  time)
 837 \end_layout
 838
 839 \begin_deeper
 840 \begin_layout Standard
 841 Request the value of a given key at a point in time
 842 \end_layout
 843
 844 \begin_layout Standard
 845 Arguments:
 846 \end_layout
 847
 848 \begin_layout Itemize
 849 var: the state variables (string)
 850 \end_layout
 851
 852 \begin_layout Itemize
 853 time: the timestamp
 854 \end_layout
 855
 856 \begin_layout Standard
 857 Return value:
 858 \end_layout
 859
 860 \begin_layout Itemize
 861 The state value.
 862  A struct state_value contains the value and the time interval that applies
 863  to it.
 864 \end_layout
 865
 866 \end_deeper
 867 \begin_layout Itemize
 868 struct state_value_range **state_get_values_in_range(char *key, struct state_val
 869 ue *val, struct trace_time_range range)
 870 \end_layout
 871
 872 \begin_deeper
 873 \begin_layout Standard
 874 Request all the state changes of a given set of state variables between
 875  two time indexes
 876 \end_layout
 877
 878 \begin_layout Standard
 879 Arguments:
 880 \end_layout
 881
 882 \begin_layout Itemize
 883 key: the key
 884 \end_layout
 885
 886 \begin_layout Itemize
 887 range: the time range
 888 \end_layout
 889
 890 \begin_layout Standard
 891 Return value:
 892 \end_layout
 893
 894 \begin_layout Itemize
 895 The values
 896 \end_layout
 897
 898 \end_deeper
 899 \begin_layout Itemize
 900 Other functions for getting values for a set of keys at once?
 901 \end_layout
 902
 903 \begin_layout Subsection
 904 Methods of the State Setting API
 905 \end_layout
 906
 907 \begin_layout Itemize
 908 set a particular state
 909 \end_layout
 910
 911 \begin_layout Itemize
 912 delete some states
 913 \end_layout
 914
 915 \begin_layout Section
 916 Describing event types
 917 \end_layout
 918
 919 \begin_layout Subsection
 920 Overview
 921 \end_layout
 922
 923 \begin_layout Standard
 924 Because tracepoints may be created dynamically, information about the descriptio
 925 n of events is just as dynamic.
 926  In this context, one simple way to communicate the event description informatio
 927 n to upper layers would be to send them as events, as it is done in recent
 928  versions of LTTV.
 929  The core events used to describe other events are the only ones whose descripti
 930 on is hardcoded in the framework.
 931 \end_layout
 932
 933 \begin_layout Standard
 934 These event-type-describing events could then be received and interpreted
 935  by the Event Description Service, which would be a client to the high-level
 936  tracing API at the same level as normal views and analyses.
 937  It would store the information and allow the other views and analyses to
 938  access it via this API.
 939 \end_layout
 940
 941 \begin_layout Standard
 942 Each event has a timestamp, a name and arguments of various types.
 943  The framework should support the following types:
 944 \end_layout
 945
 946 \begin_layout Itemize
 947 uint32
 948 \end_layout
 949
 950 \begin_layout Itemize
 951 uint64
 952 \end_layout
 953
 954 \begin_layout Itemize
 955 int32
 956 \end_layout
 957
 958 \begin_layout Itemize
 959 int64
 960 \end_layout
 961
 962 \begin_layout Itemize
 963 string
 964 \end_layout
 965
 966 \begin_layout Subsection
 967 Events-describing events
 968 \end_layout
 969
 970 \begin_layout Itemize
 971 Event type declaration event
 972 \end_layout
 973
 974 \begin_deeper
 975 \begin_layout Standard
 976 Announce the existence of an event type
 977 \end_layout
 978
 979 \begin_layout Itemize
 980 event type name
 981 \end_layout
 982
 983 \end_deeper
 984 \begin_layout Itemize
 985 Argument declaration event
 986 \end_layout
 987
 988 \begin_deeper
 989 \begin_layout Standard
 990 Announce the existence of an event argument
 991 \end_layout
 992
 993 \begin_layout Itemize
 994 event type name
 995 \end_layout
 996
 997 \begin_layout Itemize
 998 name
 999 \end_layout
1000
1001 \begin_layout Itemize
1002 type
1003 \end_layout
1004
1005 \end_deeper
1006 \begin_layout Itemize
1007 Event destruction
1008 \end_layout
1009
1010 \begin_deeper
1011 \begin_layout Standard
1012 Announce that an event type ceased to exist
1013 \end_layout
1014
1015 \begin_layout Itemize
1016 event type name
1017 \end_layout
1018
1019 \end_deeper
1020 \begin_layout Subsection
1021 Methods of the Event Type Description API
1022 \end_layout
1023
1024 \begin_layout Standard
1025 The event type description service provides the following functions.
1026 \end_layout
1027
1028 \begin_layout Itemize
1029 GArray<struct event_type *> *traceset_get_all_event_types(struct traceset
1030  *ts)
1031 \end_layout
1032
1033 \begin_deeper
1034 \begin_layout Standard
1035 Get the list of all the event types
1036 \end_layout
1037
1038 \begin_layout Standard
1039 Arguments:
1040 \end_layout
1041
1042 \begin_layout Itemize
1043 ts: the traceset of which we want the event types
1044 \end_layout
1045
1046 \begin_layout Standard
1047 Return value:
1048 \end_layout
1049
1050 \begin_layout Itemize
1051 A GArray of of struct event_type.
1052  The GArray must be gfree()'d by the caller when it is done reading it.
1053 \end_layout
1054
1055 \end_deeper
1056 \begin_layout Itemize
1057 struct event_type *traceset_get_event_type_by_name(struct traceset *ts,
1058  char *name)
1059 \end_layout
1060
1061 \begin_deeper
1062 \begin_layout Standard
1063 Find an event type by name
1064 \end_layout
1065
1066 \begin_layout Standard
1067 Arguments:
1068 \end_layout
1069
1070 \begin_layout Itemize
1071 ts: the traceset of which we want the event type
1072 \end_layout
1073
1074 \begin_layout Itemize
1075 name: the name of the of the event type we are looking for
1076 \end_layout
1077
1078 \begin_layout Standard
1079 Return value:
1080 \end_layout
1081
1082 \begin_layout Itemize
1083 A pointer to the event type (must not be free'd) or NULL if not found
1084 \end_layout
1085
1086 \end_deeper
1087 \begin_layout Itemize
1088 GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype)
1089 \end_layout
1090
1091 \begin_deeper
1092 \begin_layout Standard
1093 Get the list of arguments of an event
1094 \end_layout
1095
1096 \begin_layout Standard
1097 Arguments:
1098 \end_layout
1099
1100 \begin_layout Itemize
1101 eventype: the event type of which we want the arguments
1102 \end_layout
1103
1104 \begin_layout Standard
1105 Return value:
1106 \end_layout
1107
1108 \begin_layout Itemize
1109 A GArray of struct event_args.
1110  The GArray must be gfree()'d by the caller when it is done reading it.
1111 \end_layout
1112
1113 \end_deeper
1114 \begin_layout Itemize
1115 struct event_arg *event_type_get_arg_by_name(struct event_type *evtype)
1116 \end_layout
1117
1118 \begin_deeper
1119 \begin_layout Standard
1120 Find an argument by name
1121 \end_layout
1122
1123 \end_deeper
1124 \begin_layout Itemize
1125 Functions for accessing struct event_arg fields
1126 \end_layout
1127
1128 \begin_layout Section
1129 Inspecting events
1130 \end_layout
1131
1132 \begin_layout Subsection
1133 Overview
1134 \end_layout
1135
1136 \begin_layout Standard
1137 Events contain the following information.
1138 \end_layout
1139
1140 \begin_layout Itemize
1141 Timestamp
1142 \end_layout
1143
1144 \begin_layout Itemize
1145 Event type identifier - an event id (integer) - hidden to the API users,
1146  manipulated as pointers/references to struct event_type
1147 \end_layout
1148
1149 \begin_layout Itemize
1150 A reference to the trace it was in
1151 \end_layout
1152
1153 \begin_layout Subsection
1154 Methods of the Event inspecting API
1155 \end_layout
1156
1157 \begin_layout Itemize
1158 struct event_type *event_get_type(struct traceset *ts, struct event *ev)
1159 \end_layout
1160
1161 \begin_deeper
1162 \begin_layout Standard
1163 get the event type corresponding to an event
1164 \end_layout
1165
1166 \begin_layout Standard
1167 Arguments:
1168 \end_layout
1169
1170 \begin_layout Itemize
1171 ts:
1172 \end_layout
1173
1174 \begin_layout Itemize
1175 ev:
1176 \end_layout
1177
1178 \begin_layout Standard
1179 Return value:
1180 \end_layout
1181
1182 \begin_layout Itemize
1183 The event type or NULL if no information
1184 \end_layout
1185
1186 \end_deeper
1187 \begin_layout Itemize
1188 struct trace_time event_get_time(struct event *ev)
1189 \end_layout
1190
1191 \begin_deeper
1192 \begin_layout Standard
1193 get the event time
1194 \end_layout
1195
1196 \end_deeper
1197 \begin_layout Itemize
1198 struct trace *event_get_trace(struct event *ev)
1199 \end_layout
1200
1201 \begin_layout Itemize
1202 get the name of the machine on which the event occured or other location
1203  information
1204 \end_layout
1205
1206 \begin_layout Itemize
1207 get information on the type of tracing technology that was used
1208 \end_layout
1209
1210 \begin_layout Itemize
1211 get the corresponding tracepoint (machine/tracing technology/name/location
1212  in code(if available))
1213 \end_layout
1214
1215 \begin_layout Itemize
1216 uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg)
1217 \end_layout
1218
1219 \begin_layout Itemize
1220 int32 event_read_arg_int32(struct event *ev, struct event_arg *arg)
1221 \end_layout
1222
1223 \begin_layout Itemize
1224 uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg)
1225 \end_layout
1226
1227 \begin_layout Itemize
1228 int64 event_read_arg_int64(struct event *ev, struct event_arg *arg)
1229 \end_layout
1230
1231 \begin_layout Itemize
1232 float32 event_read_arg_float32(struct event *ev, struct event_arg *arg)
1233 \end_layout
1234
1235 \begin_layout Itemize
1236 float64 event_read_arg_float64(struct event *ev, struct event_arg *arg)
1237 \end_layout
1238
1239 \begin_layout Section
1240 Filtering events
1241 \end_layout
1242
1243 \begin_layout Standard
1244 A filtering API is proposed.
1245 \end_layout
1246
1247 \begin_layout Section
1248 Controlling the tracing of a system
1249 \end_layout
1250
1251 \begin_layout Subsection
1252 Overview
1253 \end_layout
1254
1255 \begin_layout Standard
1256 The goal of this API is to provide a portable way of controlling tracing
1257  of heterogenous systems.
1258 \end_layout
1259
1260 \begin_layout Standard
1261 It should enable to do the following actions.
1262 \end_layout
1263
1264 \begin_layout Itemize
1265 Set the parameters of a trace (channels, buffering, destination of data
1266  (file, network, process)...)
1267 \end_layout
1268
1269 \begin_layout Itemize
1270 Control the recording of events (start, stop, pause the trace)
1271 \end_layout
1272
1273 \begin_layout Itemize
1274 Create tracepoints (on dynamic tracers) and control which tracepoints are
1275  activated (some may be at trace level, others might only permit system
1276  level)
1277 \end_layout
1278
1279 \begin_layout Subsection
1280 Methods of the Trace Control API
1281 \end_layout
1282
1283 \begin_layout Itemize
1284 List the static tracepoints available on a system
1285 \end_layout
1286
1287 \begin_deeper
1288 \begin_layout Standard
1289 These may be static tracepoints (active or inactive) or dynamic tracepoints
1290  (active or proposed).
1291 \end_layout
1292
1293 \end_deeper
1294 \begin_layout Itemize
1295 Add a new dynamic tracepoint
1296 \end_layout
1297
1298 \begin_layout Itemize
1299 Activate a tracepoint
1300 \end_layout
1301
1302 \begin_layout Itemize
1303 Deactivate a tracepoint
1304 \end_layout
1305
1306 \begin_layout Itemize
1307 List available probes
1308 \end_layout
1309
1310 \begin_layout Itemize
1311 Connect a probe to a tracepoint
1312 \end_layout
1313
1314 \begin_layout Itemize
1315 Start tracing
1316 \end_layout
1317
1318 \begin_layout Itemize
1319 Stop tracing
1320 \end_layout
1321
1322 \begin_layout Itemize
1323 \begin_inset Note Greyedout
1324 status open
1325
1326 \begin_layout Standard
1327 others missing...
1328 \end_layout
1329
1330 \end_inset
1331
1332
1333 \end_layout
1334
1335 \end_body
1336 \end_document