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