Commit | Line | Data |
---|---|---|
fa62a451 | 1 | ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png) |
fffd4c7d | 2 | |
8be23338 | 3 | [![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf) |
b7c42d35 | 4 | [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf.svg)](https://ci.lttng.org/job/barectf) |
8be23338 | 5 | |
9d38bef3 | 6 | **barectf** is a command-line utility which generates C99 |
e5aa0be3 PP |
7 | code that is able to write native [Common Trace Format](http://diamon.org/ctf) |
8 | (CTF) binary streams. | |
fffd4c7d PP |
9 | |
10 | You will find barectf interesting if: | |
11 | ||
e5aa0be3 PP |
12 | 1. You need to trace an application. |
13 | 2. You need tracing to be efficient, yet flexible: | |
fffd4c7d | 14 | record integers of custom sizes, custom floating point numbers, |
e5aa0be3 PP |
15 | enumerations supported by a specific integer type, and |
16 | null-terminated UTF-8/ASCII strings (C strings). | |
fffd4c7d PP |
17 | 3. You need to be able to convert the recorded binary events to |
18 | human-readable text, as well as analyze them with Python scripts | |
cb25d862 | 19 | ([Babeltrace](http://diamon.org/babeltrace/) does all that, |
fffd4c7d PP |
20 | given a CTF input). |
21 | 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing | |
22 | framework for the Linux kernel and Linux/BSD user applications, which | |
e5aa0be3 | 23 | also outputs CTF. |
fffd4c7d PP |
24 | |
25 | The target audience of barectf is developers who need to trace bare metal | |
26 | systems (without an operating system). The code produced by barectf | |
e5aa0be3 | 27 | is pure C99 and can be lightweight enough to fit on a tiny microcontroller. |
fffd4c7d | 28 | |
e5aa0be3 | 29 | **Key features**: |
fffd4c7d | 30 | |
9d38bef3 PP |
31 | * Single input: easy-to-write [YAML configuration |
32 | file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file) | |
e5aa0be3 | 33 | * 1-to-1 mapping from tracing function parameters to event fields |
9d38bef3 PP |
34 | * Custom and bundled |
35 | [_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform) | |
36 | hiding the details of opening/closing packets and writing them to a | |
37 | back-end (continuous tracing), getting the clock values, etc.: | |
e5aa0be3 PP |
38 | * _linux-fs_: basic Linux application tracing writing stream files to |
39 | the file system for demonstration purposes | |
40 | * _parallella_: Adapteva Epiphany/[Parallella](http://parallella.org/) | |
41 | with host-side consumer | |
42 | * CTF metadata generated by the command-line tool (automatic trace UUID, | |
43 | stream IDs, and event IDs) | |
44 | * All basic CTF types are supported: integers, floating point numbers, | |
45 | enumerations, and null-terminated strings (C strings) | |
46 | * Binary streams produced by the generated C code and metadata file | |
47 | produced by barectf are CTF 1.8-compliant | |
48 | * Human-readable error reporting | |
fffd4c7d | 49 | |
e5aa0be3 | 50 | **Current limitations**: |
fffd4c7d | 51 | |
e5aa0be3 PP |
52 | As of this version: |
53 | ||
54 | * All the generated tracing C functions, for a given barectf | |
55 | stream-specific context, need to be called from the same thread, and cannot | |
56 | be called from an interrupt handler, unless a user-provided | |
57 | synchronization mechanism is used. | |
58 | * CTF compound types (array, sequence, structure, variant) are not supported | |
59 | yet, except at some very specific locations in the metadata. | |
de9eae2c PP |
60 | * The current generated C code is not strictly C99 compliant: |
61 | [statement expressions](https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html) | |
62 | and the | |
63 | [`typeof` keyword](https://gcc.gnu.org/onlinedocs/gcc/Typeof.html) | |
64 | GCC extensions are used in the generated bitfield macros. The | |
65 | generated C code is known to be compiled with no warnings using | |
66 | both GCC and Clang. | |
e5aa0be3 PP |
67 | |
68 | barectf is written in Python 3. | |
69 | ||
70 | ||
71 | ## Installing | |
72 | ||
73 | Make sure you have Python 3 and `pip` for Python 3 installed, then | |
74 | install barectf. | |
75 | ||
76 | Note that you may pass the `--user` argument to | |
77 | `pip install` to install the tool in your home directory (instead of | |
78 | installing globally). | |
79 | ||
80 | **Latest Ubuntu**: | |
fffd4c7d PP |
81 | |
82 | sudo apt-get install python3-pip | |
e5aa0be3 | 83 | sudo pip3 install barectf |
fffd4c7d | 84 | |
e5aa0be3 | 85 | **Ubuntu 12.04 and lower**: |
fffd4c7d PP |
86 | |
87 | sudo apt-get install python3-setuptools | |
88 | sudo easy_install3 pip | |
e5aa0be3 | 89 | sudo pip3 install barectf |
fffd4c7d | 90 | |
e5aa0be3 | 91 | **Debian**: |
fffd4c7d | 92 | |
e5aa0be3 | 93 | sudo apt-get install python3-pip |
fffd4c7d PP |
94 | sudo pip3 install barectf |
95 | ||
e5aa0be3 | 96 | **Fedora 20 and up**: |
fffd4c7d | 97 | |
e5aa0be3 PP |
98 | sudo yum install python3-pip |
99 | sudo pip3 install barectf | |
fffd4c7d | 100 | |
e5aa0be3 | 101 | **Arch Linux**: |
fffd4c7d | 102 | |
c119e70b | 103 | sudo pacman -S python-pip |
e5aa0be3 | 104 | sudo pip install barectf |
fffd4c7d | 105 | |
e5aa0be3 | 106 | **OS X** |
fffd4c7d | 107 | |
e5aa0be3 | 108 | With [Homebrew](http://brew.sh/): |
ca3417e6 | 109 | |
e5aa0be3 PP |
110 | brew install python3 |
111 | pip3 install barectf | |
fffd4c7d | 112 | |
fffd4c7d | 113 | |
e5aa0be3 | 114 | ## What is CTF? |
fffd4c7d | 115 | |
e5aa0be3 PP |
116 | See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell) |
117 | section of CTF's website to understand the basics of this | |
118 | trace format. | |
fffd4c7d | 119 | |
e5aa0be3 PP |
120 | The most important thing to understand about CTF, for barectf use |
121 | cases, is the layout of a binary stream packet: | |
fffd4c7d | 122 | |
e5aa0be3 PP |
123 | * Packet header (defined at the trace level) |
124 | * Packet context (defined at the stream level) | |
125 | * Sequence of events (defined at the stream level): | |
126 | * Event header (defined at the stream level) | |
127 | * Stream event context (defined at the stream level) | |
128 | * Event context (defined at the event level) | |
129 | * Event payload (defined at the event level) | |
fffd4c7d | 130 | |
e5aa0be3 PP |
131 | The following diagram, stolen without remorse from CTF's website, shows |
132 | said packet layout: | |
fffd4c7d | 133 | |
e5aa0be3 | 134 | ![](http://diamon.org/ctf/img/ctf-stream-packet.png) |
fffd4c7d | 135 | |
e5aa0be3 PP |
136 | Any of those six dynamic scopes, if defined at all, has an associated |
137 | CTF type. barectf requires them to be structure types. | |
fffd4c7d | 138 | |
fffd4c7d | 139 | |
e5aa0be3 | 140 | ## Using |
fffd4c7d | 141 | |
9d38bef3 PP |
142 | See the [project's wiki](https://github.com/efficios/barectf/wiki) which |
143 | contains all the information needed to use barectf. | |
bed7233f PP |
144 | |
145 | ||
146 | ## Testing | |
147 | ||
148 | Bash is required for testing barectf. | |
149 | ||
150 | The barectf tests execute the `barectf` command available in your | |
151 | `$PATH`. The best way to test a specific version of barectf is to create | |
152 | a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/), | |
153 | install the appropriate version, and then run the tests. | |
154 | ||
155 | In the barectf source tree root, do: | |
156 | ||
e23f0269 | 157 | virtualenv --python=python3 virt |
bed7233f PP |
158 | . ./virt/bin/activate |
159 | rehash # if using zsh | |
160 | ./setup.py install | |
161 | (cd tests && ./test.bash) | |
162 | ||
163 | You can specify [Bats](https://github.com/sstephenson/bats) options to | |
164 | `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/) | |
165 | output. | |
166 | ||
167 | You can exit the virtual environment by running `deactivate`. | |
5682f231 PP |
168 | |
169 | ||
170 | ## Community | |
171 | ||
172 | Since the barectf community is small, it's sharing the communication | |
173 | channels of the [LTTng](http://lttng.org/) project, | |
174 | as [EfficiOS](http://www.efficios.com/) is the main sponsor of both | |
175 | projects. It goes like this: | |
176 | ||
177 | | Item | Location | Notes | | |
178 | | --- | --- | --- | | |
179 | | Mailing list | [lttng-dev](https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev) (`lttng-dev@lists.lttng.org`) | Preferably, use the `[barectf]` subject prefix | | |
180 | | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode | | |
181 | | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | | | |
182 | | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | | | |
183 | | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | | | |
184 | | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | | |