README.md

   1 ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png)
   2
   3 [![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf)
   4 [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf_master_build.svg)](https://ci.lttng.org/job/barectf_master_build)
   5
   6 **barectf** is a command-line utility which generates ANSI C
   7 code that is able to write native [Common Trace Format](http://diamon.org/ctf)
   8 (CTF) binary streams.
   9
  10 You will find barectf interesting if:
  11
  12   1. You need to trace an application.
  13   2. You need tracing to be efficient, yet flexible:
  14      record integers of custom sizes, custom floating point numbers,
  15      enumerations supported by a specific integer type, and
  16      null-terminated UTF-8/ASCII strings (C strings).
  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
  19      ([Babeltrace](http://diamon.org/babeltrace/) does all that,
  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
  23      also outputs CTF.
  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
  27 is pure ANCI C (with one exception, see the current limitations below)
  28 and can be lightweight enough to fit on a tiny microcontroller.
  29
  30 **Key features**:
  31
  32   * Single input: easy-to-write [YAML configuration
  33     file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file)
  34   * 1-to-1 mapping from tracing function parameters to event fields
  35   * Custom and bundled
  36     [_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform)
  37     hiding the details of opening/closing packets and writing them to a
  38     back-end (continuous tracing), getting the clock values, etc.:
  39     * _linux-fs_: basic Linux application tracing writing stream files to
  40       the file system for demonstration purposes
  41     * _parallella_: Adapteva Epiphany/[Parallella](http://parallella.org/)
  42       with host-side consumer
  43   * CTF metadata generated by the command-line tool (automatic trace UUID,
  44     stream IDs, and event IDs)
  45   * All basic CTF types are supported: integers, floating point numbers,
  46     enumerations, and null-terminated strings (C strings)
  47   * Binary streams produced by the generated C code and metadata file
  48     produced by barectf are CTF 1.8-compliant
  49   * Human-readable error reporting
  50
  51 **Current limitations**:
  52
  53 As of this version:
  54
  55   * All the generated tracing C functions, for a given barectf
  56     stream-specific context, need to be called from the same thread, and cannot
  57     be called from an interrupt handler, unless a user-provided
  58     synchronization mechanism is used.
  59   * The generated C code needs the `stdint.h` header, which is new in
  60     C99. If your standard C library does not have this header,
  61     you can create one yourself and put it in one of your include
  62     directories to define the following types according to your
  63     architecture:
  64     * `int8_t`
  65     * `int16_t`
  66     * `int32_t`
  67     * `int64_t`
  68     * `uint8_t`
  69     * `uint16_t`
  70     * `uint32_t`
  71     * `uint64_t`
  72   * CTF compound types (array, sequence, structure, variant) are not
  73     supported yet, except at some very specific locations in the
  74     metadata.
  75
  76 barectf is written in Python 3.
  77
  78
  79 ## Installing
  80
  81 Make sure you have Python 3 and `pip` for Python 3 installed, then
  82 install barectf.
  83
  84 Note that you may pass the `--user` argument to
  85 `pip install` to install the tool in your home directory (instead of
  86 installing globally).
  87
  88 **Ubuntu 14.04 and 16.04**:
  89
  90 It is recommended to use the
  91 [barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf),
  92 which also installs the man page:
  93
  94     sudo apt-add-repository ppa:lttng/barectf
  95     sudo apt-get update
  96     sudo apt-get install python3-barectf
  97
  98 Otherwise, you can always use `pip3`:
  99
 100     sudo apt-get install python3-pip
 101     sudo pip3 install barectf
 102
 103 **Other, recent Ubuntu**:
 104
 105     sudo apt-get install python3-pip
 106     sudo pip3 install barectf
 107
 108 **Ubuntu 12.04 and lower**:
 109
 110     sudo apt-get install python3-setuptools
 111     sudo easy_install3 pip
 112     sudo pip3 install barectf
 113
 114 **Debian**:
 115
 116     sudo apt-get install python3-pip
 117     sudo pip3 install barectf
 118
 119 **Fedora 20 and up**:
 120
 121     sudo yum install python3-pip
 122     sudo pip3 install barectf
 123
 124 **Arch Linux**:
 125
 126 It is recommended to use the
 127 [AUR package](https://aur.archlinux.org/packages/barectf/), which also
 128 installs the man page. If you have
 129 [yaourt](https://archlinux.fr/yaourt-en):
 130
 131     sudo yaourt -Sy barectf
 132
 133 Otherwise, you can always use `pip`:
 134
 135     sudo pacman -S python-pip
 136     sudo pip install barectf
 137
 138 **OS X**:
 139
 140 With [Homebrew](http://brew.sh/):
 141
 142     brew install python3
 143     pip3 install barectf
 144
 145
 146 ### Man page
 147
 148 Since the philosophy of setuptools packages is to include everything
 149 within the package, the barectf man page is not installed on the system
 150 when installing barectf with `pip` or with `setup.py`. This would be the
 151 job of distribution packages.
 152
 153 You can install it manually:
 154
 155     wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
 156
 157 Replace `VERSION` with the desired version, for example:
 158
 159     wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
 160
 161
 162 ## What is CTF?
 163
 164 See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell)
 165 section of CTF's website to understand the basics of this
 166 trace format.
 167
 168 The most important thing to understand about CTF, for barectf use
 169 cases, is the layout of a binary stream packet:
 170
 171   * Packet header (defined at the trace level)
 172   * Packet context (defined at the stream level)
 173   * Sequence of events (defined at the stream level):
 174     * Event header (defined at the stream level)
 175     * Stream event context (defined at the stream level)
 176     * Event context (defined at the event level)
 177     * Event payload (defined at the event level)
 178
 179 The following diagram, stolen without remorse from CTF's website, shows
 180 said packet layout:
 181
 182 ![](http://diamon.org/ctf/img/ctf-stream-packet.png)
 183
 184 Any of those six dynamic scopes, if defined at all, has an associated
 185 CTF type. barectf requires them to be structure types.
 186
 187
 188 ## Using
 189
 190 See the [project's wiki](https://github.com/efficios/barectf/wiki) which
 191 contains all the information needed to use barectf.
 192
 193
 194 ## Testing
 195
 196 Bash is required for testing barectf.
 197
 198 The barectf tests execute the `barectf` command available in your
 199 `$PATH`. The best way to test a specific version of barectf is to create
 200 a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/),
 201 install the appropriate version, and then run the tests.
 202
 203 In the barectf source tree root, do:
 204
 205     virtualenv --python=python3 virt
 206     . ./virt/bin/activate
 207     rehash # if using zsh
 208     ./setup.py install
 209     (cd tests && ./test.bash)
 210
 211 You can specify [Bats](https://github.com/sstephenson/bats) options to
 212 `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/)
 213 output.
 214
 215 You can exit the virtual environment by running `deactivate`.
 216
 217
 218 ## Community
 219
 220 Since the barectf community is small, it's sharing the communication
 221 channels of the [LTTng](http://lttng.org/) project,
 222 as [EfficiOS](http://www.efficios.com/) is the main sponsor of both
 223 projects. It goes like this:
 224
 225 | Item | Location | Notes |
 226 | --- | --- | --- |
 227 | 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 |
 228 | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode |
 229 | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | |
 230 | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | |
 231 | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | |
 232 | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | |