Philippe Proulx [Thu, 3 Sep 2020 14:25:56 +0000 (10:25 -0400)]
barectf.c.j2: packet closing function: do not repeat member names
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 3 Sep 2020 14:22:02 +0000 (10:22 -0400)]
bitfield.h.j2: do not prefix bitfield functions
The `barectf-bitfield.h` file is only included by `barectf.c` now, so
having such prefixes is pointless.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 3 Sep 2020 14:17:01 +0000 (10:17 -0400)]
templates: commonize the licence header
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 3 Sep 2020 14:11:55 +0000 (10:11 -0400)]
templates: add licence headers to all templates
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 3 Sep 2020 04:32:20 +0000 (00:32 -0400)]
barectf/templates/metadata/*.j2: normalize
* Indent control structures.
* Do not use whitespace control when not needed.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 3 Sep 2020 01:23:56 +0000 (21:23 -0400)]
Fix: _IntegerFieldType.__init__(): use correct alignment
This patch makes _IntegerFieldType.__init__() consider `alignment` if
it's not `None` instead of completely ignoring it.
😒
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 28 Aug 2020 22:00:56 +0000 (18:00 -0400)]
_CCodeGenerator.generate_c_src(): use Jinja 2 templates
This patch makes _CCodeGenerator.generate_c_src() use Jinja 2 templates
instead of a generic code generator.
The purpose of switching to Jinja 2 templates is to make such templates
more readable than Python code, to make them reusable, and to assign
different concerns to different templates.
As such a change is hard to make incrementally, this patch changes many
parts of the tree at once. More specifically, the impacted parts are:
`gen.py`:
* _CCodeGenerator.generate_c_src() now creates _all_ the operations
(which used to be named "serialization actions"; more about this
below) for all the root field types and passes this to the
`barectf.c.j2` template at rendering time.
_CCodeGenerator.generate_c_src() doesn't use anything from
`barectf.codegen` or `barectf.templates`.
* What used to be named `_SerializationActions` is now named
`_OpsBuilder`.
An `_OpsBuilder` object does pretty much the same job as what a
`_SerializationActions` object previously did: when you call its
append_root_ft() method, it iterates the members of the structure
field type recursively to append corresponding operations to
itself. You can then get its current list of operations with its
`ops` property.
* An operation is either "align" (`_AlignOp`) or "write"
(`_WriteOp`).
Each of those operations can occur in two different contexts:
serialization or size computation. Therefore, each operation
contains two `barectf.template._Template` objects: one for the
serialization function and one for the size computation function.
You can render both templates using the serialize_str() and
size_str() methods (to which you can pass more rendering context).
Although most operations use the same generic templates, the
serialization template of some "write" operations can be custom.
This is how special fields are handled, like the packet header's
magic number or the event header's time.
In `barectf/templates/c`, template files are named as such:
+--------------------+------------------------+-------------------+
| Operation/Function | Serialization | Size |
+====================+========================+===================+
| Align | `serialize-align-*.j2` | `size-align-*.j2` |
| Write | `serialize-write-*.j2` | `size-write-*.j2` |
+--------------------+------------------------+-------------------+
* An operation contains all the names you need to craft a source
variable name (to be joined with `_`).
This is why root field type prefixes (`_RootFtPrefixes`) don't
contain a trailing underscore anymore.
The topmost name of an operation `o` is `o.top_name`; templates
mostly use this property for C comments.
`template.py`:
`codegen.py`:
Both files are removed as they're no longer needed by the project.
`templates/c`:
`barectf.c.j2`:
New template which generates the whole `barectf.c` file (given
the file name prefix is `barectf`).
This template generates, in this order:
* The licence header.
* Utility C macros.
* Internal data structures.
* Public barectf context access funtions.
* Internal functions.
* Public barectf context initialization function.
* For each stream type:
* Public packet opening function.
* Public packet closing function.
* Internal event header serialization function.
* Internal event common context serialization function.
* For each event type:
* Internal serialization function.
* For each event type:
* Internal size computation function.
* For each event type:
* Public tracing function.
`barectf.c-macros.j2`:
Macros to be used by the `barectf.c.j2` template:
* open_close_func_preamble()
* ft_call_params()
`common.j2`:
New trace_func_name() and op_src() macros.
`align-statements-comment.j2`:
C comment for any alignment statement.
`serialize-align-statements.j2`:
Alignment statements for serialization functions.
`serialize-write-*statements.j2`:
Writing statements for serialization functions.
`serialize-write-statements-comment.j2`:
C comment for generic writing statements (for serialization
functions).
`size-align-statements.j2`:
Alignment statements for size computation functions.
`size-write-*-statements.j2`:
Writing statements for size computation functions.
Also, to make templates simpler, I standardized the following C
variable names:
`ctx`:
Generic barectf context.
`sctx`:
Stream-type-specific barectf context.
`vctx`:
`ctx` as a `void` pointer.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 28 Aug 2020 14:45:05 +0000 (10:45 -0400)]
tsdl182gen.py: remove unused `jinja2` import
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 19:51:52 +0000 (15:51 -0400)]
_CCodeGenerator.generate_header(): use Jinja 2 templates
This patch makes _CCodeGenerator.generate_header() generate the main
barectf header file using Jinja 2 templates.
The master template, `barectf.h.j2`, includes:
`c-common.j2`:
Common macros for C templates.
`c-ctx-init-func-proto.j2`:
Context initialization function prototype.
`c-open-func-proto.j2`:
Packet opening function prototype.
`c-close-func-proto.j2`:
Packet closing function prototype.
`c-trace-func-proto.j2`:
Tracing function prototype.
This patch removes a lot of code from `gen.py` and `templates.py` which
now has its equivalent in Jinja 2 templates.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 17:37:30 +0000 (13:37 -0400)]
Add `common.j2` template
This file can contain common variables and macros.
It is to be imported by other templates, for example by `bitfield.h.j2`
in this patch.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 17:37:00 +0000 (13:37 -0400)]
Jinja 2 templates: stylize block comments like C block comments
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 15:59:21 +0000 (11:59 -0400)]
barectf.h: do not include `barectf-bitfield.h`
The public header itself doesn't need the macros of
`barectf-bitfield.h`; it only pollutes the global namespace with
internal macro names.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 15:45:30 +0000 (11:45 -0400)]
bitfield.h.j2: prefix `CAST_PTR` with the uppercase identifier prefix
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 15:35:47 +0000 (11:35 -0400)]
_CCodeGenerator.generate_bitfield_header(): use a Jinja 2 template
Benefits:
* `\` instead of `\\` in the template.
* Jinja 2 variables instead of `$PREFIX`, `$prefix$`, etc. which makes
it possible to have template syntax highlighting for example.
* `LITTLE_ENDIAN` or `BIG_ENDIAN` generated by the template using the
barectf configuration.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 15:34:40 +0000 (11:34 -0400)]
gen.py: add _CCodeGenerator._create_{file_}template() methods
Those new methods create a template (or a file template) using the C
code generator's barectf configuration.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 27 Aug 2020 15:11:16 +0000 (11:11 -0400)]
template.py: define a `_Template` class instead of two functions
This patch changes `template.py` so as to offer the `_Template` class
instead of the _create_template() and _render_template() functions.
This makes it possible to move the `is_file_template` parameter from
_render_template() to the template's constructor, as this really is a
template-specific option, not a rendering-specific option.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 20 Aug 2020 19:52:48 +0000 (15:52 -0400)]
Use Jinja 2 templates to generate the `metadata` file
The goal of this patch is to, as much as possible, and as long as
everything remains as readable as possible, move any `metadata` file
templating outside of pure Python code to improve template readability,
maintenability, and reuse.
This patch does the following:
1. Adds a Jinja 2 dependency to `pyproject.toml`.
2. Adds the `template` module which contains helpers to create and
render a Jinja 2 template.
The _create_template() function uses a `jinja2.PackageLoader` object
to load a named package from the `barectf` packet's `templates`
directory.
It creates an environment with common parameters and common
filters:
`indent_tab`:
Like Jinja 2's built-in `indent`, but uses tabs instead of
spaces.
`escape_sq`:
Escapes a double-quoted string (backslashes and double quotes).
Jinja 2 templates can expect to have access to the `barectf_config`
and `barectf_version` modules, as well as, possibly, the current
barectf configuration as the `cfg` variable.
The _render_template() function renders a given template with a given
context, keeping a single newline at the end if `is_file_template` is
`True`.
3. Adds Jinja 2 templates to generate the `metadata` file:
`metadata.j2`:
Top-level template for the whole file.
`metadata-enum-ft.j2`:
Enumeration field type block template.
`metadata-int-ft.j2`:
Integer field type block template.
`metadata-real-ft.j2`:
Real field type block template.
`metadata-str-ft.j2`:
String field type block template.
`metadata-struct-ft.j2`:
Structure field type block template.
4. Changes `barectf/tsdl182gen.py` so as to use 2. with 3.
`barectf/tsdl182gen.py` defines custom Jinja 2 filters to help the
templates of 3.:
`bo_str`:
Converts a `barectf.ByteOrder` value to the `le` or `be` string.
`disp_base_int`:
Converts a `barectf.DisplayBase` value to an equivalent integer.
`int_ft_str`:
Converts an integer field type object to its TSDL string
equivalent.
The first line is not indented.
`ft_str`:
Converts any field type object to its TSDL string equivalent.
The first line is not indented.
5. Adds the `barectf.TraceType.clock_types` property to easily access
the set of required clock types (by all stream types).
This is required by 3.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 11 Aug 2020 20:27:54 +0000 (16:27 -0400)]
cli.py: fix Pylint errors
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 11 Aug 2020 18:33:35 +0000 (14:33 -0400)]
Add Python type hints
This patch adds Python type hints to all the modules except
`codegen.py`, `gen.py`, and `tsdl182gen.py`, as it is likely that those
will change significantly in the future.
Mypy 0.782 reports no errors with this patch.
The few errors that were found during the type hint introduction process
are fixed as part of this patch.
`typing.py` is a new module which contains public and private type
aliases, mostly derivatives of `int` to add semantics (index, count,
version number, and the rest). The ones that are public are available
from the `barectf` package itself (`__init__.py`). A `barectf` API user
doesn't need to use them without static type checking needs. If she
wants to, then she must use `barectf` types explicitly, for example:
import barectf
clk_type = barectf.ClockType('my_clock',
frequency=barectf.Count(100000))
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 10 Aug 2020 20:44:36 +0000 (16:44 -0400)]
v3 YAML config: require `$default-byte-order` property
CTF 1.8 consumers require the `trace` block's `byte_order` property, so
let's require it in barectf too for the moment.
We can relax this requirement later if possible.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Sat, 8 Aug 2020 01:37:55 +0000 (21:37 -0400)]
__init__.py: remove `barectf_config_file` name
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Sat, 8 Aug 2020 01:00:52 +0000 (21:00 -0400)]
cli.py: fix wrong comment
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 7 Aug 2020 21:39:55 +0000 (17:39 -0400)]
cli: add short command descriptions to their help text
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 7 Aug 2020 21:35:56 +0000 (17:35 -0400)]
cli: add `--help` usage and description in command help texts
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 7 Aug 2020 21:32:24 +0000 (17:32 -0400)]
cli: add `show-configuration-version` command
This new command prints either `2` or `3` on a single line depending on
the major version of the given configuration file, for example:
$ barectf show-configuration-version my-config.yaml
2
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 7 Aug 2020 21:17:13 +0000 (17:17 -0400)]
cli: add `show-effective-configuration` command
This new command is equivalent to `generate --dump-config`, but in a
more dedicated way:
$ barectf show-effective-configuration config.yaml
It only accepts relevant options.
One of the options is `--indent-spaces` which controls the indentation
space count of printed YAML lines.
This patch deprecates `--dump-config`: I'll leave it working in
barectf 3 to remain backward-compatible, but I'm removing it from the
`generate` command's help.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 7 Aug 2020 19:21:15 +0000 (15:21 -0400)]
cli: introduce Git-like commands
This patch makes the barectf CLI work with commands like Git:
$ barectf COMMAND COMMAND-ARGS
The goal of this change is to have the `barectf` tool perform more than
tracer generation in the future. For instance, the current
`--dump-config` option should be a dedicated command instead of being
part of the generation process.
As of this patch, the only available command is `generate` (with a `gen`
alias) which does exactly what `barectf` does without an explicit
command:
$ barectf generate config.yaml
$ barectf config.yaml
`--help` and `--version` are "general" options; you need to put them
before the command name, if any:
$ barectf --help
$ barectf --version
You can also put `--help` after the command name to get this command's
help:
$ barectf generate --help
`argpar.py` is a Python equivalent of the low-level parts of
<https://github.com/efficios/argpar> which I originally wrote for
Babeltrace 2.
While I acknowledge that it's ludicrous to write a custom argument
parser in Python considering that the standard library and PyPI packages
offer many of them, I couldn't find one which can satisfy the "default
command" use case, with this default command accepting a non-option
argument. For:
$ barectf config.yaml
all of them indicate that `config.yaml` is not a valid command name.
Of course this is because there's ambiguity when your configuration file
happens to be named `generate` in the current working directory:
$ barectf generate
This can also be the `generate` command with a missing configuration
file path. As of this patch, this is what happens: `barectf` prefers the
command name. It is such a corner case that I'm not spending ONE MINUTE
on it. That being said, there's a workaround:
$ barectf ./generate
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 30 Jul 2020 14:43:43 +0000 (10:43 -0400)]
Fix: add missing `tests/config/2/fail/metadata` directory
Was ignored because `tests/config/.gitignore` ignores `metadata` files
(and directories).
Unignore `tests/config/2/fail/metadata` in `tests/config/.gitignore`.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 30 Jul 2020 13:56:29 +0000 (09:56 -0400)]
Fix: remove import cycles from `config.py`
Now `config.py` contains the configuration objects and `config_file.py`
the configuration file functions.
This made barectf fail on Python 3.6.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 29 Jul 2020 14:49:51 +0000 (10:49 -0400)]
Use barectf.cli._run() as the CLI's starting function
I don't want to expose barectf.cli.run().
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 29 Jul 2020 14:31:30 +0000 (10:31 -0400)]
Add package inclusion dir. at the API level
This patch adds a `with_package_inclusion_directory` boolean parameter
(true by default) to the barectf.effective_configuration_file() and
barectf.configuration_from_file() functions.
If this new parameter is true, then the package inclusion directory
(`barectf/include/2` or `barectf/include/3`, depending on the
configuration file's version) is appended to the provided inclusion
directories.
This patch moves this logic from the CLI module to the configuration
modules. It is my understanding that users would want to be able to
include package YAML files using only the API. In `cli.py`,
_parse_args() now simply appends the current working directory, so that
the order stays the same:
1. `--include-dir` options, in order.
2. Current working directory.
3. Package inclusion directory.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 27 Jul 2020 21:00:01 +0000 (17:00 -0400)]
tox.ini: keep a single `pylint` environment (warnings + errors)
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 27 Jul 2020 20:59:39 +0000 (16:59 -0400)]
tox.ini: rename `pep8` environment to `flake8`
That's the tool's name.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 27 Jul 2020 19:38:11 +0000 (15:38 -0400)]
Introduce new barectf configuration API and YAML configuration schema
This patch:
* Updates the configuration API (breaking change) to:
* Match, more or less, Babeltrace 2's terminology.
* Be more clear and consistent.
* Prepare for CTF 2.
* Adds support for a new type of YAML configuration to match the updated
configuration API.
Internally, the new schema is named "v3" as it will be barectf 3's
configuration format. The (now) old schema is named "v2".
* Updates all the existing code to deal with the updated configuration
API.
I admit that this is a very big change, but it was too arduous to split
in various patches. This message explains what changes and why.
Configuration API changes (metadata)
====================================
barectf 2's metadata API has existed for five years now.
During those five years, I had the chance to work on Babeltrace 2,
CTF 2, and LTTng, and polished CTF's concepts, type relations, and
terminology.
The main goal of this patch is, as much as possible, to make barectf's
configuration API match what was done in Babeltrace 2's trace IR API [1]
at the metadata level.
A few examples:
* All metadata objects are "types" (classes in Babeltrace 2): field
type, clock type, event type, stream type, and so on.
* A signed enumeration field type inherits an enumeration field type
(which inherits an integer field type) and a signed integer field
type.
* Integer and string field types have no encoding property.
If we need them, we can introduce text array field types in the
future.
A string field type has a fixed UTF-8 (a superset of ASCII) encoding.
With this patch, an integer field type doesn't have any property
mapping. Instead, when you create a stream type, you can specify a
default clock type: the event time and packet beginning/end time members
refer to this default clock type in the generated TSDL metadata stream
so that each stream has an instance of it.
One other important change is that, with this patch, you cannot specify:
* The packet header field type of a trace type.
* The packet context field type of a stream type.
* The event header field type of a stream type.
I believe it was an error to let the user control those structure field
types as, fundamentally, they are "format" field types (reserved by
CTF).
As of this patch, you can enable/disable trace type and stream type
features which eventually translate to the automatic creation of the
field types listed above. For example, the "discarded events counter
field type" feature of a stream type controls whether or not the packets
of its instances (streams) contain a discarded events counter field. You
can either:
* Disable the feature (`None`).
* Enable the feature with a default field type (`DEFAULT_FIELD_TYPE`).
* Enable the feature with a custom field type
(`UnsignedIntegerFieldType` instance).
The packet context field type is a bit of an exception here as it can
contain both format (total size, content size, beginning/end times, and
the rest) and user members. As such, when you create a stream type, you
can specify extra packet context field type members.
This feature approach hides all the reserved CTF member names (`id`,
`magic`, `uuid`, `timestamp_begin`, and the rest): barectf deals with
this internally. There are sane defaults, for example:
* The "magic" and "stream type ID" trace type features are enabled by
default.
* If, when you create a stream type, you specify a default clock type
and default features, then the event time and packet beginning/end
times features are enabled.
All the configuration names are in `config.py` (removing `metadata.py`).
The big picture is:
* A configuration has a trace and options (prefixes and other generation
options).
* A trace has an environment (think TSDL environment) and a type.
* A trace type has a default byte order, a UUID, features, and one or
more stream types.
* A stream type has an ID, a name, an default clock type,
features, extra packet context field type members, a common event
context field type, and one or more event types.
* A clock type has a name, a frequency, a UUID, a description, a
precision, an offset, and whether or not its origin is the Unix epoch.
* An event type has an ID, a name, a log level, and specific context and
payload field types.
* A field type (abstract) has an alignment.
* A bit array field type (abstract) adds the size (bits) and byte order
properties to a field type.
* An integer field type adds the preferred display base properties to a
bit array field type.
* An enumeration field type adds the mappings property to an integer
field type.
* A real field type is a bit array field type.
The only valid sizes are 32 (single-precision) and 64
(double-precision).
* An array field type (abstract) adds element field type property to a
field type.
* A static array field type adds the length property to an array field
type.
This field type is only used for the "UUID field type" trace type
feature.
* A structure field type has named members.
Each member has a field type.
In the future (CTF 2), a structure field type member could also
contain custom user attributes.
New YAML configuration schema
=============================
The barectf 3 YAML configuration format mirrors the new configuration
API, with some sugar to make it easier to write a YAML configuration
file.
The most significant changes are:
* There's no configuration version property.
Starting from barectf 3, a barectf YAML configuration node is a map
with the YAML tag [2] `tag:barectf.org,2020/3/config`. Consequently, a
barectf 3 YAML configuration file will typically start like this:
%YAML 1.2
--- !<tag:barectf.org,2020/3/config>
As you can see, the barectf major version is encoded within the tag.
The major version is enough: minor bumps of barectf 3 will only add
features without breaking the schema.
Only the configuration node needs an explicit tag: all the nodes under
it have implicit tags according to the schema. This top-level tag
makes it possible to integrate a barectf 3 configuration node within
another YAML document, if this ever becomes a use case.
* The terminology, the property names, and, in general, the object
layouts, are the same as with the configuration API.
* There are two ways to specify prefixes:
Single prefix:
Use `PREFIX_` for C identifiers, where `PREFIX` is the single
prefix, and `PREFIX` for file names.
For example, with
prefix: hello
identifiers start with `hello_` and file names with `hello`.
Explicit prefixes:
Specify the exact prefixes to be used for C identifiers and file
names.
For example, with
prefix:
identifier: lol_
file-name: meow
identifiers start with `lol_` and file names with `meow`.
* For the trace type and stream types, specify features in the
`$features` property.
Example:
$features:
magic-field-type: true
uuid-field-type: false
stream-type-id-field-type:
class: unsigned-int
size: 8
byte-order: le
A field type feature can be one of:
True:
Use the default field type.
False:
Disable the feature.
Field type node:
Use a specific field type.
* The only way to make a stream type the default stream type is with its
`$is-default` property.
Example:
my_stream:
$is-default: true
Only one stream type can have this property set to true.
* Specify field type aliases with any order, whatever the dependencies.
Example:
$field-type-aliases:
hello:
$inherit: meow
alignment: 32
meow:
class: signed-int
size: 32
* An enumeration field type is an integer field type; there's no concept
of "value field type" anymore.
Example:
 class: unsigned-enum
size: 32
byte-order: le
mappings:
# ...
* An enumeration field type's `mappings` property is a map of labels to
lists of integer ranges.
The order of individual mappings is not important.
An integer range is either a single integer or a pair of integers
(lower and upper).
Example:
 class: unsigned-enum
size: 32
mappings:
HOLA: [2]
MEOW:
- 23
- [4, 17]
ROCK:
- [1000, 2000]
- [3000, 4000]
- [5000, 6000]
* A real field type is a bit array field type.
Example (single-precision):
 class: real
size: 32
* Specify the members of a structure field type like a YAML ordered
map [3], without having to specify the `tag:yaml.org,2002:omap`
tag.
This fixes a "bug" which exists since barectf 2.0: a YAML map is not
ordered per se; as such, the members of a structure field type cannot
be a simple map. It works in barectf 2 because PyYAML parses the map
entries in order, but there's no requirement to do so.
Example:
class: struct
members:
- sup:
field-type: uint32
- meow:
field-type:
class: string
- bob:
field-type:
$inherit: double
byte-order: be
It might seem silly to specify `field-type` for each member, but CTF 2
might bring user attributes for individual structure field type
members, so barectf 3 will be ready. For example:
class: struct
members:
- sup:
field-type: uint32
- meow:
field-type:
class: string
user-attributes:
'https://example.com/ns/ctf':
type: user-name
color: blue
- bob:
field-type:
$inherit: double
byte-order: be
Internally, barectf detects the YAML configuration file's version. If
it's a barectf 2 configuration node, it converts it to a barectf 3
configuration node, and then it decodes it, as such:
barectf 2 YAML barectf 3 YAML
config. node -> config node. -> barectf config. object (API)
What you get with `--dump-config` occurs after step 1.
barectf 3 will remain fully backward compatible regarding barectf 2 YAML
configurations and the CLI. This is why the `barectf/include` directory
contains inclusion files for both barectf 2 and 3: the CLI selects the
appropriate directory based on the detected version.
`barectf/schemas` also contains JSON schemas for both versions of the
configuration, as well as common schemas.
Configuration API changes (functions)
=====================================
The configuration API functions are now:
configuration_file_major_version():
Returns the major version (2 or 3) of a YAML configuration file-like
object.
effective_configuration_file():
Returns the effective configuration file (YAML string) using a
file-like object and a list of inclusion directories.
An effective configuration file is a file where:
* All field type nodes are expanded (aliases and inheritance).
* Log level aliases are substituted for their integral equivalents.
* Some properties are normalized.
For example, the `be` byte order becomes `big-endian` (both are
valid). Also, null properties are simply removed.
configuration_from_file():
Returns a `barectf.Configuration` object from a YAML configuration
file-like object.
Code generation API
===================
This patch also brings changes to the code generation API.
Now you create a `barectf.CodeGenerator` object, passing a barectf
configuration.
With such a code generator object, call its generate_c_headers(),
generate_c_sources(), and generate_metadata_stream() methods to generate
code.
generate_c_headers() and generate_c_sources() return lists of
`barectf.gen._GeneratedFile` objects. Such an object contains the name
of the file and its (UTF-8 text) contents.
generate_metadata_stream() returns a single `barectf.gen._GeneratedFile`
object.
`__init__.py`
=============
The whole barectf API is now available directly under its package.
`__init__.py` picks what needs to be exposed from its different modules.
Tests
=====
Tests which were directly under `tests/config` are moved to
`tests/config/2` as we could add barectf 3 configuration tests in the
future.
[1]: https://babeltrace.org/docs/v2.0/libbabeltrace2/group__api-tir.html
[2]: https://yaml.org/spec/1.2/spec.html#id2761292
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 27 Jul 2020 19:37:08 +0000 (15:37 -0400)]
poetry.lock: update
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 1 Jun 2020 15:17:27 +0000 (11:17 -0400)]
Rename `msg`/`ctx` properties 👉 `message`/`context`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 22:12:19 +0000 (18:12 -0400)]
barectf: use package names (do not import "from")
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 21:58:26 +0000 (17:58 -0400)]
cli.py: fix PEP 8 errors, as reported by `flake8`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 21:56:49 +0000 (17:56 -0400)]
cli.py: format
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 21:56:00 +0000 (17:56 -0400)]
cli.py: standardize `exc` as exception name
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 21:54:05 +0000 (17:54 -0400)]
cli.py: replace `'...'.format(...)` with f-strings
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 20:53:13 +0000 (16:53 -0400)]
config_parse.py: replace `'...'.format()` with f-strings
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 20:52:21 +0000 (16:52 -0400)]
pyproject.toml: require Python 3.6+
I want to use f-strings.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:57:17 +0000 (15:57 -0400)]
config_parse.py: fix PEP 8 errors, as reported by `flake8`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:56:33 +0000 (15:56 -0400)]
tox.ini: make `flake8` ignore `templates.py`
`templates.py` is only a bunch of strings; no application code there.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:56:11 +0000 (15:56 -0400)]
tox.ini: run `flake8` for the `barectf` directory only
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:47:55 +0000 (15:47 -0400)]
config_parse.py: comment `_ConfigParseErrorCtx` and `_ConfigParseError`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:35:31 +0000 (15:35 -0400)]
_YamlConfigParser: rename field type creation methods (more explicit)
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:33:18 +0000 (15:33 -0400)]
_YamlConfigParser: rename `_root_yaml_path` 👉 `_root_path`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:30:52 +0000 (15:30 -0400)]
config_parse.py: use a `_YamlConfigParser` object a single time
This patch changes `_YamlConfigParser` so that you can only use it once:
the object parses the file on construction, and then makes the
configuration object available through its `config` property.
Because you can't parse another file with the same parser, we don't need
to care about any stale state.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 19:21:49 +0000 (15:21 -0400)]
config_parse.py: normalize exception contexts and messages
This patch also changes the terminology of the messages to use "type"
and "field type" as much as possible, for example "event type",
"stream type", and "integer field type".
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 16:48:49 +0000 (12:48 -0400)]
config_parse.py: update/improve comments
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 29 May 2020 15:29:03 +0000 (11:29 -0400)]
barectf: rename `ConfigParseError` 👉 `_ConfigParseError`
This is not a class which the API user can instantiate.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 28 May 2020 20:32:52 +0000 (16:32 -0400)]
barectf: use JSON schema to validate special root field type fields
This patch removes almost everything from the
`_MetadataSpecialFieldsValidator` class, moving those checks to the
`schemas/2/config/config.yaml` JSON schema instead.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 28 May 2020 18:18:48 +0000 (14:18 -0400)]
barectf: schemas: use conditionals intead of `oneOf` when possible
Using `if`/`then`/`else` instead of `oneOf` makes the `jsonschema`
validator create much more readable errors.
For example:
Before:
Error:
Configuration: Cannot create configuration from YAML file
`config.yaml`
Configuration object:
`metadata` property:
`clocks` property:
`some_clock` property:
`offset` property:
`seconds` property: -2 is not valid under any of the given
schemas: -2 is less than the minimum of 0; -2 is not of type
'null' (from schema `2/config/config`)
Now:
Error:
Configuration: Cannot create configuration from YAML file
`config.yaml`
Configuration object:
`metadata` property:
`clocks` property:
`some_clock` property:
`offset` property:
`seconds` property: -2 is less than the minimum of 0
(from schema `2/config/config`)
This is because, with conditionals, we assume that the user intended
something with some valid schema, and add more constraints. The example
above is for an integer having a minimum value of 0, or a null value. As
soon as we know that the value is an integer, then we know its minimum
must be 0; we decide to not care about the fact that the whole value
could also be null (which the old message indicated). In my opinion,
this is a better UX.
The example above is simple. For more complex schemas, the UX gain is
even more obvious.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 28 May 2020 18:16:47 +0000 (14:16 -0400)]
_SchemaValidator.validate(): use "element" prefix for array elements
Otherwise the context's object name would be:
`2` property
instead of
Element 2
for example.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 27 May 2020 03:04:48 +0000 (23:04 -0400)]
LICENSE: reflow licence header for 72 columns
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 27 May 2020 03:04:32 +0000 (23:04 -0400)]
LICENSE: update copyright years
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 27 May 2020 03:02:30 +0000 (23:02 -0400)]
barectf: reflow licence headers for 72 columns
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 27 May 2020 03:00:16 +0000 (23:00 -0400)]
barectf: update copyright years
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 27 May 2020 02:58:10 +0000 (22:58 -0400)]
gen.py, templates.py: replace double quotes with backticks (generated)
Style preference.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 27 May 2020 02:54:36 +0000 (22:54 -0400)]
cli.py, config_parse.py: replace double quotes with backticks
Style preference.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 22 May 2020 15:06:31 +0000 (11:06 -0400)]
Use JSON schemas to validate the layout and types of the YAML config.
This patch changes `config_parse.py` so as to use JSON schemas
(<https://json-schema.org/>) to validate many aspects of a barectf YAML
configuration file instead of having redundant, manual checks.
JSON schemas are found in the `barectf` package's `schemas` directory by
an instance of the new `_SchemaValidator` class. Such an object finds
all the YAML files in the `schemas` directory and, for each of them:
1. Loads it (YAML to Python dictionary).
2. Gets its ID (`$id` property).
3. Adds the schema (1.) to a local schema store using its ID (2.).
Then _SchemaValidator.validate() uses this schema store to build a JSON
schema reference resolver and validator from the `jsonschema` package
(<https://pypi.org/project/jsonschema/>).
The `jsonschema` dependency is added to `pyproject.toml` and
`poetry.lock`. We need a version which supports JSON Schema draft 7
because we need the conditional keywords (`if`/`then`).
Because the barectf YAML configuration file format supports features
which do not exist natively in YAML (inclusions, field type aliases,
field type inheritance, and log level aliases), we can't have a single
JSON schema for the "raw" configuration file. There are actually five
validation steps, each one having its JSON schema:
1. Make sure the configuration object is minimally valid, that is, it's
an object and has a `version` property with a supported value.
Schema: `config/config-min.yaml`.
2. Make sure the configuration object is valid for the inclusion phase.
Those schemas only validate that the metadata/stream/event objects
are objects and that any `$include` property is valid.
Each time the YAML configuration parser loads a partial YAML file for
inclusion, it validates the resulting object using the corresponding
schema depending on what's being included.
Knowing those objects are valid as such is enough to process
inclusions without caring about the resulting configuration object's
validity.
Schemas:
* `2/config/clock-pre-include.yaml`
* `2/config/config-pre-include.yaml`
* `2/config/event-pre-include.yaml`
* `2/config/include-prop.yaml`
* `2/config/metadata-pre-include.yaml`
* `2/config/stream-pre-include.yaml`
* `2/config/trace-pre-include.yaml`
3. Make sure the configuration object is valid for the field type
expansion phase.
This schema digs into compound field types recursively to make sure
any field type is either a string (field type alias) or an object
with either a `class` property or an `$inherit`/`inherit` (mutually
exclusive) property.
Knowing the configuration object is valid as such is enough to expand
field types without caring about the resulting configuration object's
validity. So, for example, a resulting, expanded field type could be:
class: string
size: 16
value-type:
class: array
meow: mix
We just don't care at this point, as long as field types are
"complete".
Schema: `2/config/config-pre-field-type-expansion.yaml`.
4. Make sure the configuration object is valid for the log level
expansion phase.
This schema validates the `$log-levels` property of the metadata
object as well as the `log-level` property of any event object.
Knowing the configuration object is valid as such is enough to expand
log levels, that is, to replace log level strings with their numeric
value, without caring about the resulting configuration object's
validity.
Schema: `2/config/config-pre-log-level-expansion.yaml`.
5. Make sure the configuration object is valid.
This validates the final, effective configuration object which, at
this point, do not contain any:
* `$include` properties.
* Strings as field types.
* `$inherit`/`inherit` properties (field type objects).
* `$log-levels` property (metadata object).
* Strings for the `log-level` properties (event objects).
Also, this is the configuration object which the `--dump-config`
option prints now.
* `2/config/byte-order-prop.yaml`
* `2/config/config.yaml`
* `2/config/field-type.yaml`
* `2/config/uuid-prop.yaml`
After step 5., there's not much to validate in `config_parse.py` itself:
* Make sure referred clock type objects (in `property-mappings` properties
of integer field type objects) exist.
* Make sure identifiers are valid (the schemas do not always validate
that they exclude CTF keywords for technical reasons).
* Make sure alignment values are valid (powers of two).
* Make sure there's only one default stream type name and that it
exists.
* Make sure the values of enumeration field type members are within the
field type's range depending on the value (integer) field type's size.
* Everything that remains in `_BarectfMetadataValidator`.
* Everything in `_MetadataSpecialFieldsValidator`, which is untouched
because that's not something we validate with JSON schemas, although
we could possibly, but it might stretch the use case.
_SchemaValidator.validate() catches a `jsonschema` exception and
converts it to a barectf `ConfigParseError` exception to avoid leaking
`jsonschema` objects (implementation detail) from barectf calls. I made
an effort to make the error object as readable as possible, for example
converting the instance path to context object names, but there's room
for improvement here.
No functional change intended, except for the modified raised
`ConfigParseError` objects. Tests are not changed and pass.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Wed, 20 May 2020 18:58:16 +0000 (14:58 -0400)]
config_parse.py: add _append_error_ctx() to remove redundant code
_append_error_ctx() appends context to a given `ConfigParseError`
exception and then reraises it.
Using
catch ConfigParseError as exc:
_append_error_ctx(exc, 'My object', 'My message')
instead of
catch ConfigParseError as exc:
exc.append_ctx('My object', 'My message')
raise
makes sure we don't forget to reraise.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 21:12:39 +0000 (17:12 -0400)]
Make configuration and metadata objects immutable
This patch changes how configuration and metadata objects are built.
Before this patch, the YAML configuration parser in `config.py` created
default metadata objects and then set their properties as it parsed the
YAML node.
Having such mutable objects means they can change at anytime once they
exist.
This patch changes this so that all configuration and metadata objects
accept all they need at construction time and do not offer setters.
`config.py` now only contains the `Config` and `ConfigOptions` classes
as well as the from_file() function. All the YAML parsing and
configuration/metadata construction is in `config_parse.py`.
In `config_parse.py`, there are mutable "pseudo" classes which
correspond to the immutable versions. They are only used during the
parsing stage and, at the end, converted to their public, immutable
equivalents.
The configuration validation is done at the YAML/pseudo level, which
means the public configuration/metadata classes do not validate anything
(narrow contract). Their constructors _should_ at least assert that
everything looks okay, but this work is not part of this patch.
No functional changes intended by this patch at the CLI level, which is
why all tests still pass without modification.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:55:14 +0000 (15:55 -0400)]
Capitalize exception messages and what the CLI prints
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:35:00 +0000 (15:35 -0400)]
test.bash: pass all `.bats` files to `bats`
This makes `bats` accumulate tests and run all of them with a global
progress, which is much better.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:31:59 +0000 (15:31 -0400)]
barectf_config_check_fail(): check that failure is caused by cfg. error
This patch makes barectf_config_check_fail() in `config/common.bash`
check that the output of `barectf` contains the string
configuration: cannot create configuration
so as to ensure that the failure is _at least_ caused by a configuration
error, even if we don't know if the real failure cause matches what the
test intends to verify.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:31:33 +0000 (15:31 -0400)]
tests/config/pass/everything/pass.bats: quote `$CC`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:31:11 +0000 (15:31 -0400)]
tests/config/pass/everything/pass.bats: make test directory the CWD
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:30:34 +0000 (15:30 -0400)]
tests/config/fail/yaml/invalid.yaml: fix invalid YAML (list/neg. value)
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:29:46 +0000 (15:29 -0400)]
cli: print traceback for unknown exceptions
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 19:28:59 +0000 (15:28 -0400)]
Append context to a `ConfigError` instead of wrapping another exception
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 15 May 2020 01:42:48 +0000 (21:42 -0400)]
Remove everything related to CTF sequences and variants
Those CTF types are not supported by barectf currently, yet some code
was written to support them at the configuration level. This is some
rather complex (dead) code to resolve field paths and validate those
types, but without anything to test it. In fact, the code exists to
parse a variant type, for example, but barectf fails with an error (not
supported) when you do so.
The code is still in this repository's history; let's add it back when
we can really test it.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 14 May 2020 19:22:09 +0000 (15:22 -0400)]
Convert project to a Poetry project
Poetry <https://python-poetry.org/> handles the build creation and
`setup.py` and `PKG-INFO` generation.
Poetry also handles dependencies and can create a corresponding virtual
environment having them installed.
Poetry can also publish.
`poetry.lock` was generated by `poetry install` and ensures this
specific version of barectf is tested with those specific versions of
the dependencies.
Setuptools is a run-time dependency for its `pkg_resources` package. I
use `*` for its version constraint because somehow Poetry needs
Setuptools itself so it skips this dependency (see
<https://github.com/python-poetry/poetry/issues/1584>). The `setuptools`
dependency still ends up in `setup.py`.
`tox.ini` is calibrated so that tox doesn't manage any dependency;
everything is done through Poetry (except `flake8` which doesn't need
barectf to be installed).
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 14 May 2020 16:47:24 +0000 (12:47 -0400)]
barectf/__init__.py: build version string instead of parsing it
This is more natural and less complicated.
Leaving get_version_tuple() as some modules use it.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Michael Jeanson [Tue, 4 Jun 2019 15:52:19 +0000 (11:52 -0400)]
Add git-review config
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Change-Id: I12ee3f57fc2e9cafb74cd489add4f8dbb89b2ca9
Philippe Proulx [Mon, 25 Mar 2019 20:28:03 +0000 (16:28 -0400)]
barectf v2.3.1
Signed-off-by: Philippe Proulx <pproulx@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Mon, 25 Mar 2019 20:05:13 +0000 (16:05 -0400)]
Fix: do not sample clock when closing/opening a packet for an event not fitting
This patch adds members to the generated barectf context to save the
current (becomes last) event's timestamp and use it when closing and
opening packets when the event does not fit the current packet instead
of sampling the clock again.
Without this patch, with this scenario:
1. Application calls a tracing function.
2. Tracing function samples the clock.
3. Event does not fit the current packet size: current packet is closed,
sampling the clock, and new packet is opened, also sampling the
clock.
4. Event is serialized to the new packet.
The new packet's timestamp is greater than its first event's timestamp,
because this event's timestamp is the result of sampling the clock
before sampling it to close the current packet and open a new one.
Babeltrace 1 accepts and reads the resulting stream, but Babeltrace 2's
muxer is more strict and refuses a message which is in the past.
Signed-off-by: Philippe Proulx <pproulx@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Fri, 11 Jan 2019 21:52:35 +0000 (16:52 -0500)]
Fix: use the same actions to compute event size and to serialize
Issue
=====
In `gen.py`, the code to generate the event size computation C code and
the event serialization C code are not the same. There are optimizations
to avoid generating useless alignment statements in one which are
missing in the other, and those optimizations have a bug. This bug can
lead to the space reservation phase of a tracing function passing
(enough space for a given event to serialize), but the serialization
phase writing passed the end of the packet buffer.
Solution
========
Make barectf use the exact same actions to generate the event size
computation C code and the event serialization C code.
In `gen.py`, `_SerializationActions` is a new class of which you can
use an instance to append a root scope field type
(_SerializationActions.append_root_scope_type()) and to retrieve a list
of resulting serialization actions. The two types of serialization
actions are:
`_AlignSerializationAction`:
Force the alignment of the current bit position within the packet.
`_SerializeSerializationAction`:
Serialize a field from a given type.
Each action object contains:
* An optional field type which is responsible for the action.
* An offset within the current byte when this action needs
to be executed (to generate the appropriate bt_bitfield_write_*()
calls).
* A list of names which identify this action (complete field name/path).
_SerializationActions.append_root_scope_type() performs the necessary
optimizations (does not align when specific conditions are met to avoid
a useless alignment statement). Then those optimizations apply to both
the event size computation and event serialization C code, the only
difference being that the event size computation code adds to a partial
sum variable instead of writing to the packet buffer.
The alignment optimization technique is straightforward at this point
and could be improved: if the alignment requirement did not change since
the last alignment, and if there's no padding between a field and the
previous field, then do not align for this field; otherwise, align.
Known drawbacks
===============
Because the alignment optimization technique is changed to be simpler,
some barectf configurations could make barectf generate more C code
(which means more compiled code and slower execution eventually).
However, the previously generated C code was incorrect anyway.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 17 Oct 2017 21:40:57 +0000 (17:40 -0400)]
barectf v2.3.0
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 17 Oct 2017 21:30:40 +0000 (17:30 -0400)]
tox.ini: no `pep8` env by default, fix testenv:pep8 env
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 17 Oct 2017 21:30:18 +0000 (17:30 -0400)]
barectf/config.py: fix whitespaces (PEP 8)
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Michael Jeanson [Tue, 17 Oct 2017 20:43:21 +0000 (16:43 -0400)]
tox: Add usedevelop
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Michael Jeanson [Tue, 17 Oct 2017 20:36:59 +0000 (16:36 -0400)]
Fix: fail tests succeed on env failure
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Philippe Proulx [Tue, 17 Oct 2017 19:25:25 +0000 (15:25 -0400)]
tests/common.bash: use $status, not $?, when using `run`
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 17 Oct 2017 19:11:40 +0000 (15:11 -0400)]
Merge branch 'tox' of https://github.com/mjeanson/barectf
Michael Jeanson [Tue, 17 Oct 2017 18:45:42 +0000 (14:45 -0400)]
Add tox support
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Philippe Proulx [Tue, 17 Oct 2017 18:53:10 +0000 (14:53 -0400)]
Merge branch 'master' of https://github.com/mjeanson/barectf
Philippe Proulx [Tue, 17 Oct 2017 18:52:16 +0000 (14:52 -0400)]
Fix: templates.py: call bt_piecewise_rshift() with _vtype (BE)
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Michael Jeanson [Tue, 17 Oct 2017 18:50:48 +0000 (14:50 -0400)]
Fix: return proper exit code on test failure
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Philippe Proulx [Sat, 19 Nov 2016 19:23:18 +0000 (14:23 -0500)]
linux-fs-simple example Makefile: make platform depend on barectf.h
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Sat, 19 Nov 2016 19:00:14 +0000 (14:00 -0500)]
Add tracing activity and tracing section API
The new barectf_is_tracing_enabled() function allows the instrumented
program to enable or disable tracing for a specific barectf context.
This is a thread-safe API, in that it only sets a member of the context
to 0 or 1. Disabling the tracing activity does not guarantee, however,
that the current packet or back-end is not currently being altered. See
the next paragraph about this.
The new barectf_is_in_tracing_section() function allows the instrumented
program to know if its tracing thread is currently in a barectf section
or not. barectf_is_in_tracing_section_ptr() returns a volatile pointer
to this same information.
Both functions can be used together to implement a snapshot action for a
given platform, something like:
1. The instrumented thread calls the barectf tracing functions during
its execution. When a packet is closed, the platform appends it to a
ring buffer, overwriting the oldest recorded one if there's no space
left. This is called a flight recorder mode.
2. The controller (another thread of the instrumented program, or an
external host) recognizes a trigger where we would only need the
latest data to analyze the situation. Therefore tracing must be
stopped, because we don't want the current ring buffer packets to be
overwritten anymore.
3. The controller disables tracing. It is safe to call
barectf_is_tracing_enabled(ctx, 0) from another thread.
4. When barectf_is_tracing_enabled(ctx, 0) is called, the barectf
tracing function currently being executed still needs to finish. At
this point it could still alter the current packet. Therefore the
controller waits until barectf_is_in_tracing_section() is 0.
5. Once barectf_is_in_tracing_section() returns 0, it won't return 1
until barectf_is_tracing_enabled(ctx, 1) is called again, so it is
safe to read the ring buffer, and also to read the current packet.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 15 Nov 2016 18:08:59 +0000 (13:08 -0500)]
README.md: fix links
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 15 Nov 2016 18:00:46 +0000 (13:00 -0500)]
barectf v2.2.1
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 15 Nov 2016 17:55:48 +0000 (12:55 -0500)]
README.md: update content
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Tue, 15 Nov 2016 17:13:32 +0000 (12:13 -0500)]
doc/examples: use -ansi flag to ensure ANSI C compatibility
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 10 Nov 2016 22:33:19 +0000 (17:33 -0500)]
barectf(1): write short option's argument too
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 10 Nov 2016 22:19:43 +0000 (17:19 -0500)]
Claim to generate ANSI C code
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Philippe Proulx [Thu, 10 Nov 2016 22:17:52 +0000 (17:17 -0500)]
Remove <stdint.h> include in generated bitfield.h
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
This page took 0.047624 seconds and 4 git commands to generate.