doc/examples/barectf-tracepoint/README.md

   1 # Example using `barectf-tracepoint.h`
   2
   3 This example is based on the [linux-fs-simple example](../linux-fs-simple)
   4 example, but it uses the `tracepoint()` macro defined in
   5 [`barectf-tracepoint.h`](../../../extra/barectf-tracepoint.h) instead of
   6 calling the generated tracing functions directly.
   7
   8 This example also shows the compatibility with
   9 [LTTng-UST](http://lttng.org/) that this `barectf-tracepoint.h` allows.
  10
  11 This example also includes a QEMU ARM target to simulate barectf used by
  12 a true bare-metal application.
  13
  14 All the targets of this example use the same application source:
  15 [`barectf-tracepoint.c`](barectf-tracepoint.c).
  16
  17
  18 ## barectf tracing
  19
  20 ### linux-fs platform
  21
  22 #### Building
  23
  24 Do:
  25
  26     make -f Makefile.barectf-linux-fs
  27
  28
  29 #### Running
  30
  31 Run this example:
  32
  33     ./barectf-tracepoint-barectf-linux-fs
  34
  35 The complete CTF trace is written to the `ctf-linux-fs` directory.
  36
  37 You may run the example with any arguments; they will be recorded,
  38 as string fields in the events of the binary stream, e.g.:
  39
  40     ./barectf-tracepoint-barectf-linux-fs this argument and this one will be recorded
  41
  42
  43 ### QEMU ARM platform
  44
  45 #### Building
  46
  47 To build this example, you need an ARM cross-compiler toolchain
  48 (`gcc-arm-none-eabi`, `binutils-arm-none-eabi`, and
  49 `libnewlib-arm-none-eabi` Ubuntu packages), then do:
  50
  51     make -f Makefile.barectf-qemu-arm-uart
  52
  53
  54 #### Running
  55
  56 To run this example, you need `qemu-system-arm` (`qemu-system-arm`
  57 Ubuntu package).
  58
  59 Run this example:
  60
  61     make -f Makefile.barectf-qemu-arm-uart sim
  62
  63 The complete CTF trace is written to the `ctf-qemu-arm-uart` directory.
  64
  65
  66 #### What happens when running?
  67
  68 When you run this example, here's what happens:
  69
  70   1. The `barectf-tracepoint-barectf-qemu-arm-uart.sh` Bash script
  71      is executed.
  72   2. This Bash script executes `qemu-system-arm` with the appropriate
  73      options to simulate the bare-metal application on an ARM system.
  74      The simulated board is a Versatile platform baseboard from ARM. The
  75      simulated CPU is an ARM926EJ-S. This is a 2001 ARM9 core
  76      implementing the ARMv5TE architecture. QEMU is set to execute the
  77      `barectf-tracepoint-barectf-qemu-arm-uart` ELF file (previously
  78      built), and to connect the board's first UART with QEMU's standard
  79      input/output streams, and the board's second UART to the
  80      `ctf-qemu-arm-uart/stream` file (output only). The Bash script
  81      reads each line printed by QEMU, and kills the QEMU process when
  82      it reads the ending line written by the bare-metal application.
  83   3. QEMU starts. Eventually, the bare-metal application's
  84      `main()` function is called.
  85   4. `main()` calls `init_tracing()`, which for this example, calls
  86      `barectf_platform_qemu_arm_uart_init()`. This is a custom barectf
  87      platform created specifically for this example. The platform
  88      initializes a barectf context to get its clock source from a timer
  89      on the simulated board, and to flush its packets by writing the
  90      bytes to the second UART (which is connected to the
  91      `ctf-qemu-arm-uart/stream` file by QEMU). The platform uses a
  92      global buffer of 4 kiB to hold the current packet.
  93   5. `main()` calls `trace_stuff()` which contains the `tracepoint()`
  94      macro invocations. Events are recorded to the current packet by
  95      the barectf machinery. When this packet is full, it is flushed
  96      by the platform to the second UART.
  97   6. `main()` calls `fini_tracing()`, which calls
  98      `barectf_platform_qemu_arm_uart_fini()`, which prints the
  99      ending line that `barectf-tracepoint-barectf-qemu-arm-uart.sh`
 100      is waiting for to kill QEMU.
 101
 102
 103 ## LTTng-UST tracing
 104
 105 ### Building
 106
 107 Make sure [LTTng-UST](http://lttng.org/) is installed.
 108
 109 Do:
 110
 111     make -f Makefile.lttng-ust
 112
 113
 114 ### Running
 115
 116 Create an LTTng tracing session:
 117
 118     lttng create my-session
 119
 120 Enable the events of this example:
 121
 122     lttng enable-event --userspace 'barectf_tp:*'
 123
 124 Start tracing:
 125
 126     lttng start
 127
 128 Run this example:
 129
 130     ./barectf-tracepoint-lttng-ust
 131
 132 You may run the example with any arguments; they will be recorded,
 133 as string fields in the events of the binary stream, e.g.:
 134
 135     ./barectf-tracepoint-lttng-ust this argument and this one will be recorded
 136
 137 Stop tracing and inspect the recorded events:
 138
 139     lttng stop
 140     lttng view