Permalink
Browse files

README.md: update content

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
  • Loading branch information...
eepp committed Nov 15, 2016
1 parent 17587cc commit 033bfe31192eb7596bf7baa05e45636b6a3c841a
Showing with 39 additions and 32 deletions.
  1. +38 −31 README.md
  2. +1 −1 setup.py
View
@@ -3,58 +3,67 @@
[![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf)
[![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf_master_build.svg)](https://ci.lttng.org/job/barectf_master_build)
**barectf** is a command-line utility which generates ANSI C
code that is able to write native [Common Trace Format](http://diamon.org/ctf)
(CTF) binary streams.
_**barectf**_ is a command-line generator of ANSI C tracers which output
[Common Trace Format](http://diamon.org/ctf) packets natively.
You will find barectf interesting if:
1. You need to trace an application.
2. You need tracing to be efficient, yet flexible:
record integers of custom sizes, custom floating point numbers,
enumerations supported by a specific integer type, and
null-terminated UTF-8/ASCII strings (C strings).
2. You need tracing to be efficient, yet flexible: record integers of
custom sizes and alignments, floating point numbers, enumerations
supported by a specific integer type, and null-terminated
UTF-8/ASCII strings (C strings).
3. You need to be able to convert the recorded binary events to
human-readable text, as well as analyze them with Python scripts
([Babeltrace](http://diamon.org/babeltrace/) does all that,
given a CTF input).
given a CTF input). [Trace Compass](http://tracecompass.org/) is
another CTF-compatible application.
4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing
framework for the Linux kernel and Linux/BSD user applications, which
also outputs CTF.
framework for the Linux kernel and Linux/BSD user applications,
which also outputs CTF traces.
The target audience of barectf is developers who need to trace bare metal
systems (without an operating system). The code produced by barectf
is pure ANCI C (with one exception, see the current limitations below)
and can be lightweight enough to fit on a tiny microcontroller.
The target audience of barectf is developers who need to trace [bare
metal](https://en.wikipedia.org/wiki/Bare_machine) systems. The code
produced by barectf is pure ANCI C (with one exception, see the current
limitations below) and can be lightweight enough to fit on a tiny
microcontroller.
**Key features**:
* Single input: easy-to-write [YAML configuration
file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file)
* 1-to-1 mapping from tracing function parameters to event fields
file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file).
* 1-to-1 mapping from tracing function parameters to event fields.
* Custom and bundled
[_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform)
hiding the details of opening/closing packets and writing them to a
back-end (continuous tracing), getting the clock values, etc.:
* _linux-fs_: basic Linux application tracing writing stream files to
the file system for demonstration purposes
* _parallella_: Adapteva Epiphany/[Parallella](http://parallella.org/)
with host-side consumer
* CTF metadata generated by the command-line tool (automatic trace UUID,
stream IDs, and event IDs)
* _linux-fs_: basic Linux application tracing platform which writes
stream files to the file system for demonstration purposes.
* _parallella_: Adapteva
Epiphany/[Parallella](http://parallella.org/) with host-side
consumer.
* CTF metadata is generated by the command-line tool (automatic trace
UUID, stream IDs, and event IDs).
* All basic CTF types are supported: integers, floating point numbers,
enumerations, and null-terminated strings (C strings)
* Binary streams produced by the generated C code and metadata file
produced by barectf are CTF 1.8-compliant
* Human-readable error reporting
enumerations, and null-terminated strings (C strings).
* Binary streams produced by the generated tracer and metadata file
produced by barectf are CTF 1.8-compliant.
* Human-readable error reporting at generation time.
* barectf is written in Python 3, hence you can run the tool on
various platforms.
* Generated tracers are known to build with `gcc` (tested with the
IA-32, x86-64, MIPS, ARM, and AVR architectures), `g++`, `clang`,
`clang++`, [https://github.com/rui314/8cc](`8cc`),
[http://bellard.org/tcc/](`tcc`), VS2008 (with a custom `stdint.h`),
and VS2010.
**Current limitations**:
As of this version:
* All the generated tracing C functions, for a given barectf
stream-specific context, need to be called from the same thread, and cannot
be called from an interrupt handler, unless a user-provided
stream-specific context, need to be called from the same thread, and
cannot be called from an interrupt handler, _unless_ a user-provided
synchronization mechanism is used.
* The generated C code needs the `stdint.h` header, which is new in
C99. If your standard C library does not have this header,
@@ -73,8 +82,6 @@ As of this version:
supported yet, except at some very specific locations in the
metadata.
barectf is written in Python 3.
## Installing
@@ -135,7 +142,7 @@ Otherwise, you can always use `pip`:
sudo pacman -S python-pip
sudo pip install barectf
**OS X**:
**macOS (OS X)**:
With [Homebrew](http://brew.sh/):
View
@@ -43,7 +43,7 @@ def _check_python3():
setup(name='barectf',
version=barectf.__version__,
description='Generator of ANSI C code that can write native CTF',
description='Generator of ANSI C tracers which output CTF',
author='Philippe Proulx',
author_email='eeppeliteloop@gmail.com',
license='MIT',

0 comments on commit 033bfe3

Please sign in to comment.