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