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