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 \end_deeper
 314 \begin_layout Itemize
 315 struct event *current_event(struct trace *, struct cursor *cur)
 316 \end_layout
 317
 318 \begin_deeper
 319 \begin_layout Standard
 320 Arguments: none
 321 \end_layout
 322
 323 \begin_layout Standard
 324 Return:
 325 \end_layout
 326
 327 \begin_layout Itemize
 328 the event currently pointed by the position pointer
 329 \end_layout
 330
 331 \begin_layout Itemize
 332 NULL, if current_event is called on a new cursor that is positioned before
 333  the beginning of the trace
 334 \end_layout
 335
 336 \end_deeper
 337 \begin_layout Itemize
 338 int advance(struct trace *tr, struct trace_cursor *cur)
 339 \end_layout
 340
 341 \begin_deeper
 342 \begin_layout Standard
 343 Advance the cursor to the next event in the trace.
 344 \end_layout
 345
 346 \begin_layout Standard
 347 Arguments:
 348 \end_layout
 349
 350 \begin_layout Itemize
 351 tr: the trace
 352 \end_layout
 353
 354 \begin_layout Itemize
 355 cur: the cursor that should be advanced
 356 \end_layout
 357
 358 \begin_layout Standard
 359 Return value:
 360 \end_layout
 361
 362 \begin_layout Itemize
 363 The result:
 364 \end_layout
 365
 366 \begin_deeper
 367 \begin_layout Itemize
 368 Success (TRACE_ADVANCE_OK)
 369 \end_layout
 370
 371 \begin_layout Itemize
 372 The cursor was not advanced because the end of trace is reached (end of
 373  a non-live trace or of a completed live trace) (TRACE_ADVANCE_END)
 374 \end_layout
 375
 376 \begin_layout Itemize
 377 The cursor was not advanced because no new events are available at this
 378  time (with a live trace that is still running) (TRACE_ADVANCE_TRY_AGAIN)
 379 \end_layout
 380
 381 \end_deeper
 382 \end_deeper
 383 \begin_layout Itemize
 384 int seek_time(struct trace *tr, struct trace_cursor *cur, struct trace_time
 385  time)
 386 \end_layout
 387
 388 \begin_deeper
 389 \begin_layout Standard
 390 Arguments:
 391 \end_layout
 392
 393 \begin_layout Itemize
 394 tr: the trace that should be seeked
 395 \end_layout
 396
 397 \begin_layout Itemize
 398 cur: the cursor to seek
 399 \end_layout
 400
 401 \begin_layout Itemize
 402 time: the time to seek to
 403 \end_layout
 404
 405 \begin_layout Standard
 406 Return:
 407 \end_layout
 408
 409 \begin_layout Itemize
 410 0: success
 411 \end_layout
 412
 413 \begin_layout Itemize
 414 != 0: time out of range
 415 \end_layout
 416
 417 \end_deeper
 418 \begin_layout Itemize
 419 struct trace_cursor *trace_new_cursor(struct trace *tr)
 420 \end_layout
 421
 422 \begin_deeper
 423 \begin_layout Standard
 424 Return a new cursor associated to the trace.
 425  The position of this new cursor is just before the first event, therefore
 426  advance() must be called before reading the first event.
 427 \end_layout
 428
 429 \end_deeper
 430 \begin_layout Itemize
 431 struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
 432 \end_layout
 433
 434 \begin_deeper
 435 \begin_layout Standard
 436 Copy a cursor.
 437 \end_layout
 438
 439 \begin_layout Standard
 440 Arguments:
 441 \end_layout
 442
 443 \begin_layout Itemize
 444 cur: the cursor to copy
 445 \end_layout
 446
 447 \begin_layout Standard
 448 Return value:
 449 \end_layout
 450
 451 \begin_layout Itemize
 452 a new cursor that is at the same location as cur
 453 \end_layout
 454
 455 \end_deeper
 456 \begin_layout Itemize
 457 void trace_cursor_destroy(struct trace_cursor *cur)
 458 \end_layout
 459
 460 \begin_deeper
 461 \begin_layout Standard
 462 Free all resources associated to a cursor.
 463  After this call, cur is invalid.
 464 \end_layout
 465
 466 \begin_layout Standard
 467 Arguments:
 468 \end_layout
 469
 470 \begin_layout Itemize
 471 cur: the cursor to destroy
 472 \end_layout
 473
 474 \end_deeper
 475 \begin_layout Itemize
 476 struct trace_time get_time_start(struct trace *tr)
 477 \end_layout
 478
 479 \begin_deeper
 480 \begin_layout Standard
 481 Arguments:
 482 \end_layout
 483
 484 \begin_layout Itemize
 485 tr: the trace
 486 \end_layout
 487
 488 \begin_layout Standard
 489 Return:
 490 \end_layout
 491
 492 \begin_layout Itemize
 493 the timestamp of the first event in the trace
 494 \end_layout
 495
 496 \end_deeper
 497 \begin_layout Itemize
 498 struct trace_time get_time_end(struct trace *tr)
 499 \end_layout
 500
 501 \begin_deeper
 502 \begin_layout Standard
 503 Arguments: none
 504 \end_layout
 505
 506 \begin_layout Standard
 507 Return:
 508 \end_layout
 509
 510 \begin_layout Itemize
 511 the timestamp of the last event in the trace
 512 \end_layout
 513
 514 \end_deeper
 515 \begin_layout Itemize
 516 register_callback_new_event(struct trace *tr, struct trace_time after, void
 517  (*cb)(struct trace *))
 518 \end_layout
 519
 520 \begin_deeper
 521 \begin_layout Standard
 522 Register a callback that is called when a new event becomes available in
 523  a live trace.
 524  It is also called when the live trace ends.
 525 \end_layout
 526
 527 \begin_layout Standard
 528 Arguments:
 529 \end_layout
 530
 531 \begin_layout Itemize
 532 after (timestamp) : call only if the timestamp of the event is later than
 533
 534 \emph on
 535 after
 536 \end_layout
 537
 538 \begin_layout Itemize
 539 cb: the callback function
 540 \begin_inset Note Note
 541 status open
 542
 543 \begin_layout Standard
 544 specify its args and return val
 545 \end_layout
 546
 547 \end_inset
 548
 549
 550 \end_layout
 551
 552 \begin_layout Standard
 553 Return:
 554 \end_layout
 555
 556 \begin_layout Itemize
 557 Result (success or failure)
 558 \end_layout
 559
 560 \end_deeper
 561 \begin_layout Section
 562 High level reading of traces
 563 \end_layout
 564
 565 \begin_layout Standard
 566 When reading/analyzing/viewing several traces of heterogenous types, these
 567  traces are read by translator modules, which export the Low Level Trace
 568  Reading API.
 569  The traceset service then uses this API to read each of these traces individual
 570 ly, then merge them.
 571  It may apply timestamp offsetting or other synchronization techniques.
 572  To allow views and analyses to access events, it in turn exports the High
 573  Level Trace Reading API.
 574 \end_layout
 575
 576 \begin_layout Standard
 577 The goal of this API is to provide a uniform way for analyses and views
 578  to obtain large sets of trace events from a traceset (merge of many traces
 579  or a single trace).
 580 \end_layout
 581
 582 \begin_layout Subsection
 583 Methods of the high-level trace reading API
 584 \end_layout
 585
 586 \begin_layout Itemize
 587 struct request_handle *traceset_new_event_request(struct traceset *tr, struct
 588  trace_time t1, struct trace_time t2, struct event_filter *filter, void
 589  (*cb)(void *data, ), void *data)
 590 \end_layout
 591
 592 \begin_deeper
 593 \begin_layout Standard
 594 Request a range of events
 595 \end_layout
 596
 597 \begin_layout Standard
 598 Arguments:
 599 \end_layout
 600
 601 \begin_layout Itemize
 602 tr: the traceset
 603 \end_layout
 604
 605 \begin_layout Itemize
 606 t1: start timestamp
 607 \end_layout
 608
 609 \begin_layout Itemize
 610 t2: stop timestamp (special value for infinity, for live traces)
 611 \end_layout
 612
 613 \begin_layout Itemize
 614 filter: filter with complex expressions
 615 \end_layout
 616
 617 \begin_layout Itemize
 618 data: private pointer to be passed to the callback
 619 \end_layout
 620
 621 \begin_layout Standard
 622 Return:
 623 \end_layout
 624
 625 \begin_layout Itemize
 626 handle to the request for cancelling it
 627 \end_layout
 628
 629 \end_deeper
 630 \begin_layout Itemize
 631 void event_request_cancel(struct request_handle *req)
 632 \end_layout
 633
 634 \begin_deeper
 635 \begin_layout Standard
 636 Cancel a request.
 637 \end_layout
 638
 639 \begin_layout Standard
 640 Arguments:
 641 \end_layout
 642
 643 \begin_layout Itemize
 644 req: the handle to the request
 645 \end_layout
 646
 647 \end_deeper
 648 \begin_layout Subsection
 649 State management
 650 \end_layout
 651
 652 \begin_layout Standard
 653 States are key/value pairs associated with a time range.
 654  Keys can be (and generally are) duplicated as long as they do not apply
 655  to overlapping ranges.
 656 \end_layout
 657
 658 \begin_layout Standard
 659 Keys are character strings.
 660 \end_layout
 661
 662 \begin_layout Standard
 663 Values may be of various types:
 664 \end_layout
 665
 666 \begin_layout Itemize
 667 string
 668 \end_layout
 669
 670 \begin_layout Itemize
 671 uint32
 672 \end_layout
 673
 674 \begin_layout Itemize
 675 int32
 676 \end_layout
 677
 678 \begin_layout Itemize
 679 blob (binary block of arbitrary length)
 680 \end_layout
 681
 682 \begin_layout Itemize
 683 float32
 684 \end_layout
 685
 686 \begin_layout Itemize
 687 float64
 688 \end_layout
 689
 690 \begin_layout Standard
 691 The state information must be persistent between executions of the framework.
 692 \end_layout
 693
 694 \begin_layout Standard
 695 It is possible to assign a state to the range -infinity..infinity to indicate
 696  that it is global to the trace.
 697 \end_layout
 698
 699 \begin_layout Standard
 700 The key names should be hierarchical.
 701 \end_layout
 702
 703 \begin_layout Subsubsection
 704 State accessing API
 705 \end_layout
 706
 707 \begin_layout Itemize
 708 struct state_value *state_get_value_at_time(char *key, struct trace_time
 709  time)
 710 \end_layout
 711
 712 \begin_deeper
 713 \begin_layout Standard
 714 Request the value of a given key at a point in time
 715 \end_layout
 716
 717 \begin_layout Standard
 718 Arguments:
 719 \end_layout
 720
 721 \begin_layout Itemize
 722 var: the state variables (string)
 723 \end_layout
 724
 725 \begin_layout Itemize
 726 time: the timestamp
 727 \end_layout
 728
 729 \begin_layout Standard
 730 Return value:
 731 \end_layout
 732
 733 \begin_layout Itemize
 734 The state value
 735 \end_layout
 736
 737 \end_deeper
 738 \begin_layout Itemize
 739 struct state_value_range **state_get_values_in_range(char *key, struct state_val
 740 ue *val, struct trace_time_range range)
 741 \end_layout
 742
 743 \begin_deeper
 744 \begin_layout Standard
 745 Request all the states changes of a given set of state variables between
 746  two time indexes
 747 \end_layout
 748
 749 \begin_layout Standard
 750 Arguments:
 751 \end_layout
 752
 753 \begin_layout Itemize
 754 key: the key
 755 \end_layout
 756
 757 \begin_layout Itemize
 758 range: the time range
 759 \end_layout
 760
 761 \end_deeper
 762 \begin_layout Itemize
 763 Other functions for getting values for a set of keys at once?
 764 \end_layout
 765
 766 \begin_layout Subsubsection
 767 State setting API
 768 \end_layout
 769
 770 \begin_layout Itemize
 771 set a particular state
 772 \end_layout
 773
 774 \begin_layout Itemize
 775 delete some states
 776 \end_layout
 777
 778 \begin_layout Section
 779 Describing event types
 780 \end_layout
 781
 782 \begin_layout Subsection
 783 Overview
 784 \end_layout
 785
 786 \begin_layout Standard
 787 Because tracepoints may be created dynamically, information about the descriptio
 788 n of events is just as dynamic.
 789  In this context, one simple way to communicate the event description informatio
 790 n to upper layers would be to send them as events, as it is done in recent
 791  versions of LTTV.
 792  The core events used to describe other events are the only ones whose descripti
 793 on is hardcoded in the framework.
 794 \end_layout
 795
 796 \begin_layout Standard
 797 These event-type-describing events could then be received and interpreted
 798  by the Event Description Service, which would be a client to the high-level
 799  tracing API at the same level as normal views and analyses.
 800  It would store the information and allow the other views and analyses to
 801  access it via this API.
 802 \end_layout
 803
 804 \begin_layout Standard
 805 Each event has a timestamp, a name and arguments of various types.
 806  The framework should support the following types:
 807 \end_layout
 808
 809 \begin_layout Itemize
 810 uint32
 811 \end_layout
 812
 813 \begin_layout Itemize
 814 uint64
 815 \end_layout
 816
 817 \begin_layout Itemize
 818 int32
 819 \end_layout
 820
 821 \begin_layout Itemize
 822 int64
 823 \end_layout
 824
 825 \begin_layout Itemize
 826 string
 827 \end_layout
 828
 829 \begin_layout Subsection
 830 Events-describing events
 831 \end_layout
 832
 833 \begin_layout Itemize
 834 Event type declaration event
 835 \end_layout
 836
 837 \begin_deeper
 838 \begin_layout Standard
 839 Announce the existence of an event type
 840 \end_layout
 841
 842 \begin_layout Itemize
 843 event type name
 844 \end_layout
 845
 846 \end_deeper
 847 \begin_layout Itemize
 848 Argument declaration event
 849 \end_layout
 850
 851 \begin_deeper
 852 \begin_layout Standard
 853 Announce the existence of an event argument
 854 \end_layout
 855
 856 \begin_layout Itemize
 857 event type name
 858 \end_layout
 859
 860 \begin_layout Itemize
 861 name
 862 \end_layout
 863
 864 \begin_layout Itemize
 865 type
 866 \end_layout
 867
 868 \end_deeper
 869 \begin_layout Itemize
 870 Event destruction
 871 \end_layout
 872
 873 \begin_deeper
 874 \begin_layout Standard
 875 Announce that an event type ceased to exist
 876 \end_layout
 877
 878 \begin_layout Itemize
 879 event type name
 880 \end_layout
 881
 882 \end_deeper
 883 \begin_layout Subsection
 884 Event type description API
 885 \end_layout
 886
 887 \begin_layout Standard
 888 The event type description service provides the following functions.
 889 \end_layout
 890
 891 \begin_layout Itemize
 892 GArray<struct event_type *> *traceset_get_all_event_types(struct traceset
 893  *ts)
 894 \end_layout
 895
 896 \begin_deeper
 897 \begin_layout Standard
 898 Get the list of all the event types
 899 \end_layout
 900
 901 \begin_layout Standard
 902 Arguments:
 903 \end_layout
 904
 905 \begin_layout Itemize
 906 ts: the traceset of which we want the event types
 907 \end_layout
 908
 909 \begin_layout Standard
 910 Return value:
 911 \end_layout
 912
 913 \begin_layout Itemize
 914 A GArray of of struct event_type.
 915  The GArray must be gfree()'d by the caller when it is done reading it.
 916 \end_layout
 917
 918 \end_deeper
 919 \begin_layout Itemize
 920 struct event_type *traceset_get_event_type_by_name(struct traceset *ts,
 921  char *name)
 922 \end_layout
 923
 924 \begin_deeper
 925 \begin_layout Standard
 926 Find an event type by name
 927 \end_layout
 928
 929 \begin_layout Standard
 930 Arguments:
 931 \end_layout
 932
 933 \begin_layout Itemize
 934 ts: the traceset of which we want the event type
 935 \end_layout
 936
 937 \begin_layout Itemize
 938 name: the name of the of the event type we are looking for
 939 \end_layout
 940
 941 \begin_layout Standard
 942 Return value:
 943 \end_layout
 944
 945 \begin_layout Itemize
 946 A pointer to the event type (must not be free'd) or NULL if not found
 947 \end_layout
 948
 949 \end_deeper
 950 \begin_layout Itemize
 951 GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype)
 952 \end_layout
 953
 954 \begin_deeper
 955 \begin_layout Standard
 956 Get the list of arguments of an event
 957 \end_layout
 958
 959 \begin_layout Standard
 960 Arguments:
 961 \end_layout
 962
 963 \begin_layout Itemize
 964 eventype: the event type of which we want the arguments
 965 \end_layout
 966
 967 \begin_layout Standard
 968 Return value:
 969 \end_layout
 970
 971 \begin_layout Itemize
 972 A GArray of struct event_args.
 973  The GArray must be gfree()'d by the caller when it is done reading it.
 974 \end_layout
 975
 976 \end_deeper
 977 \begin_layout Itemize
 978 struct event_arg *event_type_get_arg_by_name(struct event_type *evtype)
 979 \end_layout
 980
 981 \begin_deeper
 982 \begin_layout Standard
 983 Find an argument by name
 984 \end_layout
 985
 986 \end_deeper
 987 \begin_layout Itemize
 988 Functions for accessing struct event_arg fields
 989 \end_layout
 990
 991 \begin_layout Section
 992 Inspecting events
 993 \end_layout
 994
 995 \begin_layout Subsection
 996 Overview
 997 \end_layout
 998
 999 \begin_layout Standard
1000 Events contain the following information.
1001 \end_layout
1002
1003 \begin_layout Itemize
1004 Timestamp
1005 \end_layout
1006
1007 \begin_layout Itemize
1008 Event type identifier - an event id (integer) - hidden to the API users,
1009  manipulated as pointers/references to struct event_type
1010 \end_layout
1011
1012 \begin_layout Itemize
1013 A reference to the trace it was in
1014 \end_layout
1015
1016 \begin_layout Subsection
1017 Event inspecting API
1018 \end_layout
1019
1020 \begin_layout Itemize
1021 struct event_type *event_get_type(struct traceset *ts, struct event *ev)
1022 \end_layout
1023
1024 \begin_deeper
1025 \begin_layout Standard
1026 get the event type corresponding to an event
1027 \end_layout
1028
1029 \begin_layout Standard
1030 Arguments:
1031 \end_layout
1032
1033 \begin_layout Itemize
1034 ts:
1035 \end_layout
1036
1037 \begin_layout Itemize
1038 ev:
1039 \end_layout
1040
1041 \begin_layout Standard
1042 Return value:
1043 \end_layout
1044
1045 \begin_layout Itemize
1046 The event type or NULL if no information
1047 \end_layout
1048
1049 \end_deeper
1050 \begin_layout Itemize
1051 struct trace_time event_get_time(struct event *ev)
1052 \end_layout
1053
1054 \begin_deeper
1055 \begin_layout Standard
1056 get the event time
1057 \end_layout
1058
1059 \end_deeper
1060 \begin_layout Itemize
1061 struct trace *event_get_trace(struct event *ev)
1062 \end_layout
1063
1064 \begin_layout Itemize
1065 get the name of the machine on which the event occured or other location
1066  information
1067 \end_layout
1068
1069 \begin_layout Itemize
1070 get information on the type of tracing technology that was used
1071 \end_layout
1072
1073 \begin_layout Itemize
1074 get the corresponding tracepoint (machine/tracing technology/name/location
1075  in code(if available))
1076 \end_layout
1077
1078 \begin_layout Itemize
1079 uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg)
1080 \end_layout
1081
1082 \begin_layout Itemize
1083 int32 event_read_arg_int32(struct event *ev, struct event_arg *arg)
1084 \end_layout
1085
1086 \begin_layout Itemize
1087 uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg)
1088 \end_layout
1089
1090 \begin_layout Itemize
1091 int64 event_read_arg_int64(struct event *ev, struct event_arg *arg)
1092 \end_layout
1093
1094 \begin_layout Itemize
1095 float32 event_read_arg_float32(struct event *ev, struct event_arg *arg)
1096 \end_layout
1097
1098 \begin_layout Itemize
1099 float64 event_read_arg_float64(struct event *ev, struct event_arg *arg)
1100 \end_layout
1101
1102 \begin_layout Section
1103 Filtering events
1104 \end_layout
1105
1106 \begin_layout Standard
1107 A filtering API is proposed.
1108 \end_layout
1109
1110 \begin_layout Section
1111 Controlling the tracing of a system
1112 \end_layout
1113
1114 \begin_layout Subsection
1115 Overview
1116 \end_layout
1117
1118 \begin_layout Standard
1119 The goal of this API is to provide a portable way of controlling tracing
1120  of heterogenous systems.
1121 \end_layout
1122
1123 \begin_layout Standard
1124 It should enable to do the following actions.
1125 \end_layout
1126
1127 \begin_layout Itemize
1128 Set the parameters of a trace (channels, buffering, destination of data
1129  (file, network, process)...)
1130 \end_layout
1131
1132 \begin_layout Itemize
1133 Control the recording of events (start, stop, pause the trace)
1134 \end_layout
1135
1136 \begin_layout Itemize
1137 Create tracepoints (on dynamic tracers) and control which tracepoints are
1138  activated (some may be at trace level, others might only permit system
1139  level)
1140 \end_layout
1141
1142 \begin_layout Subsection
1143 Trace control API
1144 \end_layout
1145
1146 \begin_layout Itemize
1147 List the static tracepoints available on a system
1148 \end_layout
1149
1150 \begin_deeper
1151 \begin_layout Standard
1152 These may be static tracepoints (active or inactive) or dynamic tracepoints
1153  (active or proposed).
1154 \end_layout
1155
1156 \end_deeper
1157 \begin_layout Itemize
1158 Add a new dynamic tracepoint
1159 \end_layout
1160
1161 \begin_layout Itemize
1162 Activate a tracepoint
1163 \end_layout
1164
1165 \begin_layout Itemize
1166 Deactivate a tracepoint
1167 \end_layout
1168
1169 \begin_layout Itemize
1170 List available probes
1171 \end_layout
1172
1173 \begin_layout Itemize
1174 Connect a probe to a tracepoint
1175 \end_layout
1176
1177 \begin_layout Itemize
1178 Start tracing
1179 \end_layout
1180
1181 \begin_layout Itemize
1182 Stop tracing
1183 \end_layout
1184
1185 \begin_layout Itemize
1186 \begin_inset Note Greyedout
1187 status open
1188
1189 \begin_layout Standard
1190 others missing...
1191 \end_layout
1192
1193 \end_inset
1194
1195
1196 \end_layout
1197
1198 \end_body
1199 \end_document