doc/manual.lyx

   1 #LyX 1.6.1 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 345
   3 \begin_document
   4 \begin_header
   5 \textclass article
   6 \use_default_options true
   7 \language english
   8 \inputencoding auto
   9 \font_roman default
  10 \font_sans default
  11 \font_typewriter default
  12 \font_default_family default
  13 \font_sc false
  14 \font_osf false
  15 \font_sf_scale 100
  16 \font_tt_scale 100
  17
  18 \graphics default
  19 \paperfontsize default
  20 \use_hyperref false
  21 \papersize default
  22 \use_geometry false
  23 \use_amsmath 1
  24 \use_esint 1
  25 \cite_engine basic
  26 \use_bibtopic false
  27 \paperorientation portrait
  28 \secnumdepth 3
  29 \tocdepth 3
  30 \paragraph_separation indent
  31 \defskip medskip
  32 \quotes_language english
  33 \papercolumns 1
  34 \papersides 1
  35 \paperpagestyle default
  36 \tracking_changes false
  37 \output_changes false
  38 \author ""
  39 \author ""
  40 \end_header
  41
  42 \begin_body
  43
  44 \begin_layout Title
  45 LTTng Userspace Tracer Manual
  46 \end_layout
  47
  48 \begin_layout Author
  49 Pierre-Marc Fournier
  50 \end_layout
  51
  52 \begin_layout Section
  53 What is the LTTng Userspace Tracer?
  54 \end_layout
  55
  56 \begin_layout Subsection
  57 Overview
  58 \end_layout
  59
  60 \begin_layout Standard
  61 The LTTng Userspace Tracer (UST) is a tracing system for userspace applications.
  62  It is designed to trace efficiently applications that produce events at
  63  a very high rate.
  64  UST is derived from LTTng, a tracer for the Linux kernel.
  65  It has the same trace format.
  66 \end_layout
  67
  68 \begin_layout Standard
  69 Users may choose at runtime and even at trace time what instrumentation
  70  should be activated.
  71  Custom probes may be used to trace events conditionally.
  72 \end_layout
  73
  74 \begin_layout Subsection
  75 Features
  76 \end_layout
  77
  78 \begin_layout Itemize
  79 Arbitrary number of channels
  80 \end_layout
  81
  82 \begin_layout Itemize
  83 One buffer per process (multiple threads share the same buffer)
  84 \end_layout
  85
  86 \begin_layout Itemize
  87 Early process tracing (from the beginning of the main() function)
  88 \end_layout
  89
  90 \begin_layout Itemize
  91 Support for custom probes
  92 \end_layout
  93
  94 \begin_layout Standard
  95 Still to implement:
  96 \end_layout
  97
  98 \begin_layout Itemize
  99 Support for dynamic instrumentation
 100 \end_layout
 101
 102 \begin_layout Itemize
 103 Per thread or per CPU buffers
 104 \end_layout
 105
 106 \begin_layout Standard
 107 Complementary systems:
 108 \end_layout
 109
 110 \begin_layout Itemize
 111 A extension to gdb tracepoints that will allow the tracing of applications
 112  with dynamic instrumentation is under development.
 113 \end_layout
 114
 115 \begin_layout Subsection
 116 Performance
 117 \end_layout
 118
 119 \begin_layout Section
 120 Installation
 121 \end_layout
 122
 123 \begin_layout Subsection
 124 Obtain the code
 125 \end_layout
 126
 127 \begin_layout Standard
 128 To compile UST, you need:
 129 \end_layout
 130
 131 \begin_layout Itemize
 132 the UST code
 133 \end_layout
 134
 135 \begin_layout Itemize
 136 libkcompat
 137 \end_layout
 138
 139 \begin_layout Itemize
 140 liburcu-pmf
 141 \end_layout
 142
 143 \begin_layout Subsection
 144 Configure libkcompat
 145 \end_layout
 146
 147 \begin_layout Standard
 148 Edit kcompat.h and uncomment the architecture of the target system.
 149 \end_layout
 150
 151 \begin_layout Subsection
 152 Configure libust
 153 \end_layout
 154
 155 \begin_layout Standard
 156 If the code was obtained through git, first generate a Makefile by running
 157  autogen.sh.
 158 \end_layout
 159
 160 \begin_layout Standard
 161 Then, run ./configure, specifying the directories of liburcu and libkcompat.
 162  Example:
 163 \end_layout
 164
 165 \begin_layout Standard
 166 \begin_inset listings
 167 inline false
 168 status open
 169
 170 \begin_layout Plain Layout
 171
 172 ./configure --with-urcu=/home/pmf/liburcu-pmf --with-kcompat=/home/pmf/libkcompat
 173 \end_layout
 174
 175 \end_inset
 176
 177
 178 \end_layout
 179
 180 \begin_layout Subsection
 181 Build liburcu
 182 \end_layout
 183
 184 \begin_layout Standard
 185 Go to the liburcu directory and run:
 186 \end_layout
 187
 188 \begin_layout Standard
 189 \begin_inset listings
 190 inline false
 191 status open
 192
 193 \begin_layout Plain Layout
 194
 195 make
 196 \end_layout
 197
 198 \end_inset
 199
 200
 201 \end_layout
 202
 203 \begin_layout Subsection
 204 Build ust
 205 \end_layout
 206
 207 \begin_layout Standard
 208 Go to the ust directory and run:
 209 \end_layout
 210
 211 \begin_layout Standard
 212 \begin_inset listings
 213 inline false
 214 status open
 215
 216 \begin_layout Plain Layout
 217
 218 make
 219 \end_layout
 220
 221 \end_inset
 222
 223
 224 \end_layout
 225
 226 \begin_layout Section
 227 Instrumenting an Application
 228 \end_layout
 229
 230 \begin_layout Standard
 231 In order to record a trace of events occurring in a application, the application
 232  must be instrumented.
 233  Instrumentation points resemble function calls.
 234  When the program reaches an instrumentation point, an event is generated.
 235 \end_layout
 236
 237 \begin_layout Standard
 238 There are no limitations on the type of code that may be instrumented.
 239  Multi-threaded programs may be instrumented without problem.
 240  Signal handlers may be instrumented as well.
 241 \end_layout
 242
 243 \begin_layout Standard
 244 There are two APIs to instrument programs: markers and tracepoints.
 245  Markers are quick to add and are usually used for temporary instrumentation.
 246  Tracepoints provide a way to instrument code more cleanly and are suited
 247  for permanent instrumentation.
 248 \end_layout
 249
 250 \begin_layout Subsection
 251 Markers
 252 \end_layout
 253
 254 \begin_layout Standard
 255 Markers were ported from the Linux Kernel Markers implementation.
 256  Therefore, their usage is almost identical.
 257 \end_layout
 258
 259 \begin_layout Subsubsection
 260 Inserting Markers
 261 \end_layout
 262
 263 \begin_layout Standard
 264 Adding a marker is simply a matter of insert one line in the program.
 265 \end_layout
 266
 267 \begin_layout Standard
 268 \begin_inset listings
 269 inline false
 270 status open
 271
 272 \begin_layout Plain Layout
 273
 274 #include <marker.h>
 275 \end_layout
 276
 277 \begin_layout Plain Layout
 278
 279 int main(int argc, char **argv)
 280 \end_layout
 281
 282 \begin_layout Plain Layout
 283
 284 {
 285 \end_layout
 286
 287 \begin_layout Plain Layout
 288
 289         int v;
 290 \end_layout
 291
 292 \begin_layout Plain Layout
 293
 294         char *st;
 295 \end_layout
 296
 297 \begin_layout Plain Layout
 298
 299 \end_layout
 300
 301 \begin_layout Plain Layout
 302
 303         /* ...
 304  set values of v and st ...
 305  */
 306 \end_layout
 307
 308 \begin_layout Plain Layout
 309
 310 \end_layout
 311
 312 \begin_layout Plain Layout
 313
 314         /* a marker: */
 315 \end_layout
 316
 317 \begin_layout Plain Layout
 318
 319         trace_mark(main, myevent,
 320 \begin_inset Quotes eld
 321 \end_inset
 322
 323 firstarg %d secondarg %s
 324 \begin_inset Quotes erd
 325 \end_inset
 326
 327 , v, st);
 328 \end_layout
 329
 330 \begin_layout Plain Layout
 331
 332 \end_layout
 333
 334 \begin_layout Plain Layout
 335
 336         /* a marker without arguments: */
 337 \end_layout
 338
 339 \begin_layout Plain Layout
 340
 341         trace_mark(main, myotherevent, MARK_NOARGS);
 342 \end_layout
 343
 344 \begin_layout Plain Layout
 345
 346 \end_layout
 347
 348 \begin_layout Plain Layout
 349
 350         return 0;
 351 \end_layout
 352
 353 \begin_layout Plain Layout
 354
 355 }
 356 \end_layout
 357
 358 \end_inset
 359
 360
 361 \end_layout
 362
 363 \begin_layout Standard
 364 The invocation of the trace_mark() macro requires at least 3 arguments.
 365  The first, here
 366 \begin_inset Quotes eld
 367 \end_inset
 368
 369 main
 370 \begin_inset Quotes erd
 371 \end_inset
 372
 373 , is the name of the event category.
 374  It is also the name of the channel the event will go in.
 375  The second, here
 376 \begin_inset Quotes eld
 377 \end_inset
 378
 379 myevent
 380 \begin_inset Quotes erd
 381 \end_inset
 382
 383  is the name of the event.
 384  The third is a format string that announces the names and the types of
 385  the event arguments.
 386  Its format resembles that of a printf() format string; it is described
 387  thoroughly in Appendix x.
 388 \end_layout
 389
 390 \begin_layout Standard
 391 A given Marker may appear more than once in the same program.
 392  Other Markers may have the same name and a different format string, although
 393  this might induce some confusion at analysis time.
 394 \end_layout
 395
 396 \begin_layout Subsubsection
 397 Registering the Markers
 398 \end_layout
 399
 400 \begin_layout Standard
 401 In order to inform to register the Markers present in the module, a macro
 402  must be inserted at global scope.
 403  Only one such macro is needed per exacutable or per shared object.
 404  Adding it more than once, however, is harmless.
 405 \end_layout
 406
 407 \begin_layout Standard
 408 \begin_inset listings
 409 inline false
 410 status open
 411
 412 \begin_layout Plain Layout
 413
 414 MARKER_LIB;
 415 \end_layout
 416
 417 \end_inset
 418
 419
 420 \end_layout
 421
 422 \begin_layout Subsection
 423 Tracepoints
 424 \end_layout
 425
 426 \begin_layout Standard
 427 The Tracepoints API uses the Markers, but provides a higher-level abstraction.
 428  Whereas the markers API provides limited type checking, the Tracepoints
 429  API provides more thorough type checking and discharges from the need to
 430  insert format strings directly in the code and to have format strings appear
 431  more than once if a given marker is reused.
 432 \end_layout
 433
 434 \begin_layout Standard
 435 A tracepoint in the code looks like this:
 436 \end_layout
 437
 438 \begin_layout Standard
 439 \begin_inset listings
 440 inline false
 441 status open
 442
 443 \begin_layout Plain Layout
 444
 445 #include <marker.h>
 446 \end_layout
 447
 448 \begin_layout Plain Layout
 449
 450 \end_layout
 451
 452 \begin_layout Plain Layout
 453
 454 void function()
 455 \end_layout
 456
 457 \begin_layout Plain Layout
 458
 459 {
 460 \end_layout
 461
 462 \begin_layout Plain Layout
 463
 464         int v;
 465 \end_layout
 466
 467 \begin_layout Plain Layout
 468
 469         char *st;
 470 \end_layout
 471
 472 \begin_layout Plain Layout
 473
 474 \end_layout
 475
 476 \begin_layout Plain Layout
 477
 478         /* ...
 479  set values of v and st ...
 480  */
 481 \end_layout
 482
 483 \begin_layout Plain Layout
 484
 485 \end_layout
 486
 487 \begin_layout Plain Layout
 488
 489         /* a tracepoint: */
 490 \end_layout
 491
 492 \begin_layout Plain Layout
 493
 494         trace_main_myevent(v, st);
 495 \end_layout
 496
 497 \begin_layout Plain Layout
 498
 499 }
 500 \end_layout
 501
 502 \end_inset
 503
 504
 505 \end_layout
 506
 507 \begin_layout Standard
 508 \begin_inset listings
 509 inline false
 510 status open
 511
 512 \begin_layout Plain Layout
 513
 514 DEFINE_TRACE();
 515 \end_layout
 516
 517 \end_inset
 518
 519
 520 \end_layout
 521
 522 \begin_layout Standard
 523 \begin_inset listings
 524 inline false
 525 status open
 526
 527 \begin_layout Plain Layout
 528
 529 TRACEPOINT_LIB;
 530 \end_layout
 531
 532 \end_inset
 533
 534
 535 \end_layout
 536
 537 \begin_layout Subsection
 538 Compiling the Application
 539 \end_layout
 540
 541 \begin_layout Standard
 542 See the
 543 \begin_inset Quotes eld
 544 \end_inset
 545
 546 hello
 547 \begin_inset Quotes erd
 548 \end_inset
 549
 550  directory for an example application and makefile.
 551 \end_layout
 552
 553 \begin_layout Itemize
 554 The compiler must have access to the include path for the libust headers.
 555 \end_layout
 556
 557 \begin_layout Itemize
 558 The application should be statically or dynamically linked to libust.
 559 \end_layout
 560
 561 \begin_layout Section
 562 Recording a Trace
 563 \end_layout
 564
 565 \begin_layout Standard
 566 These preliminary steps need to be done before recording a trace.
 567 \end_layout
 568
 569 \begin_layout Standard
 570 \begin_inset listings
 571 inline false
 572 status open
 573
 574 \begin_layout Plain Layout
 575
 576 Create the directory for the communication sockets.
 577  Eventually this should be somewhere in /var.
 578 \end_layout
 579
 580 \begin_layout Plain Layout
 581
 582 $ mkdir /tmp/socks
 583 \end_layout
 584
 585 \begin_layout Plain Layout
 586
 587 \end_layout
 588
 589 \begin_layout Plain Layout
 590
 591 Create the directory where ustd will write the trace.
 592  This will become configurable.
 593 \end_layout
 594
 595 \begin_layout Plain Layout
 596
 597 $ mkdir /tmp/trace
 598 \end_layout
 599
 600 \begin_layout Plain Layout
 601
 602 \end_layout
 603
 604 \begin_layout Plain Layout
 605
 606 Start the daemon
 607 \end_layout
 608
 609 \begin_layout Plain Layout
 610
 611 $ ustd
 612 \end_layout
 613
 614 \end_inset
 615
 616
 617 \end_layout
 618
 619 \begin_layout Subsection
 620 Basic Recording
 621 \end_layout
 622
 623 \begin_layout Standard
 624 Tracing on a running program is controlled with the ust helper program.
 625  Ust can start the tracing, stop the tracing, enable markers, disable markers
 626  and list the markers.
 627  Another program, ustd, is a daemon that collects the trace events and write
 628  them to a file.
 629 \end_layout
 630
 631 \begin_layout Standard
 632 In order to record a trace, the daemon must first be started with the following
 633  command.
 634 \end_layout
 635
 636 \begin_layout Standard
 637 \begin_inset listings
 638 inline false
 639 status open
 640
 641 \begin_layout Plain Layout
 642
 643 ustd
 644 \end_layout
 645
 646 \end_inset
 647
 648
 649 \end_layout
 650
 651 \begin_layout Standard
 652 Markers can be listed with the following command (for PID 1234).
 653 \end_layout
 654
 655 \begin_layout Standard
 656 \begin_inset listings
 657 inline false
 658 status open
 659
 660 \begin_layout Plain Layout
 661
 662 ust --list-markers 1234
 663 \end_layout
 664
 665 \end_inset
 666
 667
 668 \end_layout
 669
 670 \begin_layout Standard
 671 A marker can be enabled with the following command (for PID 1234).
 672 \end_layout
 673
 674 \begin_layout Standard
 675 \begin_inset listings
 676 inline false
 677 status open
 678
 679 \begin_layout Plain Layout
 680
 681 ust --enable-marker ust/mymark 1234
 682 \end_layout
 683
 684 \end_inset
 685
 686
 687 \end_layout
 688
 689 \begin_layout Standard
 690 Then, the trace can be started.
 691 \end_layout
 692
 693 \begin_layout Standard
 694 \begin_inset listings
 695 inline false
 696 status open
 697
 698 \begin_layout Plain Layout
 699
 700 ust --start-trace  1234
 701 \end_layout
 702
 703 \end_inset
 704
 705
 706 \end_layout
 707
 708 \begin_layout Standard
 709 Eventually it can be stopped and destroyed.
 710 \end_layout
 711
 712 \begin_layout Standard
 713 \begin_inset listings
 714 inline false
 715 status open
 716
 717 \begin_layout Plain Layout
 718
 719 ust --stop-trace  1234
 720 \end_layout
 721
 722 \begin_layout Plain Layout
 723
 724 ust --destroy-trace  1234
 725 \end_layout
 726
 727 \end_inset
 728
 729
 730 \end_layout
 731
 732 \begin_layout Subsection
 733 Early Tracing
 734 \end_layout
 735
 736 \begin_layout Standard
 737 Sometimes, an application must be traced as soon as it is started.
 738  In these cases, the Basic Recording method is not satisfactory, as important
 739  events may be lost before the tracing is started.
 740 \end_layout
 741
 742 \begin_layout Standard
 743 By using the Early Tracing method, it is guaranteed that the tracing is
 744  started when the execution of the main() function of the program starts.
 745 \end_layout
 746
 747 \begin_layout Standard
 748 Early Tracing may be enabled by defining the UST_TRACE environment variable
 749  to a non-empty value when the program starts.
 750  Additionally, the UST_AUTOPROBE may be set to a non-empty value to automaticall
 751 y connect all markers to the default probe.
 752  For example:
 753 \end_layout
 754
 755 \begin_layout Standard
 756 \begin_inset listings
 757 inline false
 758 status open
 759
 760 \begin_layout Plain Layout
 761
 762 # In another terminal, start the daemon.
 763 \end_layout
 764
 765 \begin_layout Plain Layout
 766
 767 ustd
 768 \end_layout
 769
 770 \begin_layout Plain Layout
 771
 772 \end_layout
 773
 774 \begin_layout Plain Layout
 775
 776 # Start
 777 \begin_inset Quotes eld
 778 \end_inset
 779
 780 prog
 781 \begin_inset Quotes erd
 782 \end_inset
 783
 784  with early tracing.
 785 \end_layout
 786
 787 \begin_layout Plain Layout
 788
 789 UST_TRACE=1 UST_AUTOPROBE=1 ./prog
 790 \end_layout
 791
 792 \end_inset
 793
 794
 795 \end_layout
 796
 797 \begin_layout Standard
 798 In order for the trace to be saved, ustd must be running when the traced
 799  program is started.
 800 \end_layout
 801
 802 \begin_layout Section
 803 Viewing and Analyzing the Trace
 804 \end_layout
 805
 806 \begin_layout Standard
 807 LTTV may be used for opening the trace.
 808  If an appropriate time source was used, it may be opened concurrently with
 809  other application traces and kernel traces.
 810 \end_layout
 811
 812 \begin_layout Section
 813 Advanced Concepts
 814 \end_layout
 815
 816 \begin_layout Subsection
 817 Using Custom Probes for Conditional Tracing
 818 \end_layout
 819
 820 \begin_layout Subsection
 821 Instrumenting Calls to Library Functions without Recompilation
 822 \end_layout
 823
 824 \begin_layout Standard
 825 Calls to uninstrumented libraries may be instrumented by creating a wrapper
 826  library that intercepts calls to the library, trigger an instrumentation
 827  point.
 828 \end_layout
 829
 830 \begin_layout Standard
 831 Such an example can be found in the libmallocwrap directory of the ust code
 832  package.
 833 \end_layout
 834
 835 \begin_layout Subsection
 836 Tracing Programs Without Linking them to the Tracing Library
 837 \end_layout
 838
 839 \begin_layout Standard
 840 Programs that were not instrumented nor linked with the tracing libraries
 841  may still be traced.
 842  In order to produce events, they must be linked to instrumented libraries
 843  or use instrumented library wrappers as described in section xx.
 844 \end_layout
 845
 846 \begin_layout Standard
 847 \begin_inset listings
 848 inline false
 849 status open
 850
 851 \begin_layout Plain Layout
 852
 853 LD_PRELOAD=...
 854  program
 855 \end_layout
 856
 857 \end_inset
 858
 859
 860 \end_layout
 861
 862 \begin_layout Section
 863 \start_of_appendix
 864 Format of Marker Format Strings
 865 \end_layout
 866
 867 \begin_layout Standard
 868 The format of Marker format strings is inspired from printf() format strings.
 869  As with printf(), it is used to indicate to the parsing function the type
 870  of the arguments that are passed.
 871  Additionally, format strings indicate the name of each argument and the
 872  format of that argument in the trace.
 873  The structure of a typical format string is the following.
 874 \end_layout
 875
 876 \begin_layout Standard
 877 \begin_inset listings
 878 inline false
 879 status open
 880
 881 \begin_layout Plain Layout
 882
 883 \begin_inset Quotes eld
 884 \end_inset
 885
 886 field_name1 #tracetype1 %ctype1 field_name2 #tracetype2 %ctype2
 887 \begin_inset Quotes erd
 888 \end_inset
 889
 890
 891 \end_layout
 892
 893 \end_inset
 894
 895
 896 \end_layout
 897
 898 \begin_layout Description
 899 field_name: The name of the field, as it will be seen when the trace is
 900  parsed.
 901 \end_layout
 902
 903 \begin_layout Description
 904 tracetype: The type of the argument as it will be written in the trace.
 905 \end_layout
 906
 907 \begin_layout Description
 908 ctype: The C type of the argument passed to the Marker (this is very similar
 909  to the %...
 910  types in a printf() format string)
 911 \end_layout
 912
 913 \begin_layout Standard
 914 Both field_name and tracetype are optional.
 915  These are all valid format strings:
 916 \end_layout
 917
 918 \begin_layout Standard
 919 \begin_inset listings
 920 inline false
 921 status open
 922
 923 \begin_layout Plain Layout
 924
 925 \end_layout
 926
 927 \end_inset
 928
 929
 930 \end_layout
 931
 932 \begin_layout Subsection
 933 tracetype
 934 \end_layout
 935
 936 \begin_layout Standard
 937 A typical Marker format string looks like this:
 938 \end_layout
 939
 940 \begin_layout Standard
 941 The serialization format string supports the basic printf format strings.
 942 \end_layout
 943
 944 \begin_layout Standard
 945 In addition, it defines new formats that can be used to serialize more
 946 \end_layout
 947
 948 \begin_layout Standard
 949 complex/non portable data structures.
 950 \end_layout
 951
 952 \begin_layout Standard
 953 Typical use:
 954 \end_layout
 955
 956 \begin_layout Standard
 957 field_name %ctype
 958 \end_layout
 959
 960 \begin_layout Standard
 961 field_name #tracetype %ctype
 962 \end_layout
 963
 964 \begin_layout Standard
 965 field_name #tracetype %ctype1 %ctype2 ...
 966 \end_layout
 967
 968 \begin_layout Standard
 969 A conversion is performed between format string types supported by GCC and
 970 \end_layout
 971
 972 \begin_layout Standard
 973 the trace type requested.
 974  GCC type is used to perform type checking on format
 975 \end_layout
 976
 977 \begin_layout Standard
 978 strings.
 979  Trace type is used to specify the exact binary representation
 980 \end_layout
 981
 982 \begin_layout Standard
 983 in the trace.
 984  A mapping is done between one or more GCC types to one trace
 985 \end_layout
 986
 987 \begin_layout Standard
 988 type.
 989  Sign extension, if required by the conversion, is performed following
 990 \end_layout
 991
 992 \begin_layout Standard
 993 the trace type.
 994 \end_layout
 995
 996 \begin_layout Standard
 997 If a gcc format is not declared with a trace format, the gcc format is
 998 \end_layout
 999
1000 \begin_layout Standard
1001 also used as binary representation in the trace.
1002 \end_layout
1003
1004 \begin_layout Standard
1005 Strings are supported with %s.
1006 \end_layout
1007
1008 \begin_layout Standard
1009 A single tracetype (sequence) can take multiple c types as parameter.
1010 \end_layout
1011
1012 \begin_layout Standard
1013 c types:
1014 \end_layout
1015
1016 \begin_layout Standard
1017 see printf(3).
1018 \end_layout
1019
1020 \begin_layout Standard
1021 Note: to write a uint32_t in a trace, the following expression is recommended
1022 \end_layout
1023
1024 \begin_layout Standard
1025 si it can be portable:
1026 \end_layout
1027
1028 \begin_layout Standard
1029 ("#4u%lu", (unsigned long)var)
1030 \end_layout
1031
1032 \begin_layout Standard
1033 trace types:
1034 \end_layout
1035
1036 \begin_layout Standard
1037 Serialization specific formats :
1038 \end_layout
1039
1040 \begin_layout Standard
1041 Fixed size integers
1042 \end_layout
1043
1044 \begin_layout Standard
1045 #1u writes uint8_t
1046 \end_layout
1047
1048 \begin_layout Standard
1049 #2u writes uint16_t
1050 \end_layout
1051
1052 \begin_layout Standard
1053 #4u writes uint32_t
1054 \end_layout
1055
1056 \begin_layout Standard
1057 #8u writes uint64_t
1058 \end_layout
1059
1060 \begin_layout Standard
1061 #1d writes int8_t
1062 \end_layout
1063
1064 \begin_layout Standard
1065 #2d writes int16_t
1066 \end_layout
1067
1068 \begin_layout Standard
1069 #4d writes int32_t
1070 \end_layout
1071
1072 \begin_layout Standard
1073 #8d writes int64_t
1074 \end_layout
1075
1076 \begin_layout Standard
1077 i.e.:
1078 \end_layout
1079
1080 \begin_layout Standard
1081 #1u%lu #2u%lu #4d%lu #8d%lu #llu%hu #d%lu
1082 \end_layout
1083
1084 \begin_layout Standard
1085 * Attributes:
1086 \end_layout
1087
1088 \begin_layout Standard
1089 n: (for network byte order)
1090 \end_layout
1091
1092 \begin_layout Standard
1093 #ntracetype%ctype
1094 \end_layout
1095
1096 \begin_layout Standard
1097 is written in the trace in network byte order.
1098 \end_layout
1099
1100 \begin_layout Standard
1101 i.e.: #bn4u%lu, #n%lu, #b%u
1102 \end_layout
1103
1104 \begin_layout Standard
1105 TODO (eventually)
1106 \end_layout
1107
1108 \begin_layout Standard
1109 Variable length sequence
1110 \end_layout
1111
1112 \begin_layout Standard
1113 #a #tracetype1 #tracetype2 %array_ptr %elem_size %num_elems
1114 \end_layout
1115
1116 \begin_layout Standard
1117 In the trace:
1118 \end_layout
1119
1120 \begin_layout Standard
1121 #a specifies that this is a sequence
1122 \end_layout
1123
1124 \begin_layout Standard
1125 #tracetype1 is the type of elements in the sequence
1126 \end_layout
1127
1128 \begin_layout Standard
1129 #tracetype2 is the type of the element count
1130 \end_layout
1131
1132 \begin_layout Standard
1133 GCC input:
1134 \end_layout
1135
1136 \begin_layout Standard
1137 array_ptr is a pointer to an array that contains members of size
1138 \end_layout
1139
1140 \begin_layout Standard
1141 elem_size.
1142 \end_layout
1143
1144 \begin_layout Standard
1145 num_elems is the number of elements in the array.
1146 \end_layout
1147
1148 \begin_layout Standard
1149 i.e.: #a #lu #lu %p %lu %u
1150 \end_layout
1151
1152 \begin_layout Standard
1153 Callback
1154 \end_layout
1155
1156 \begin_layout Standard
1157 #k callback (taken from the probe data)
1158 \end_layout
1159
1160 \begin_layout Standard
1161 The following % arguments are exepected by the callback
1162 \end_layout
1163
1164 \begin_layout Standard
1165 i.e.: #a #lu #lu #k %p
1166 \end_layout
1167
1168 \begin_layout Standard
1169 Note: No conversion is done from floats to integers, nor from integers to
1170 \end_layout
1171
1172 \begin_layout Standard
1173 floats between c types and trace types.
1174  float conversion from double to float
1175 \end_layout
1176
1177 \begin_layout Standard
1178 or from float to double is also not supported.
1179 \end_layout
1180
1181 \begin_layout Section
1182 Environment variables
1183 \end_layout
1184
1185 \begin_layout Standard
1186 The following environment variables change the behavior of libust.
1187 \end_layout
1188
1189 \begin_layout Description
1190 UST_TRACE When defined, automatically enables tracing.
1191 \end_layout
1192
1193 \begin_layout Description
1194 UST_AUTOPROBE When value is 1, enable all markers automatically.
1195  When value is a regular expression, enable all markers whose name matches
1196  the regular expression.
1197 \end_layout
1198
1199 \begin_layout Description
1200 UST_DAEMON_SOCKET If not set, the default location of the daemon socket
1201  is used.
1202  If set, the value is used as path to the ustd socket.
1203 \end_layout
1204
1205 \end_body
1206 \end_document