| 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 |