docs: cleanup: Rephrase and correct typos

`docs/modules/how-barectf-works/pages/index.adoc`:
    - Facilitate understanding for beginners (Make sentence structure
      more explicit, Use more explicit terms)

`docs/modules/platform/pages/index.adoc`:
    - "recommandation" --> "recommendation"
    - Remove "as its document"

Change-Id: I00e123a348cb90b53aed5effcde7f9ecdbbae453
Signed-off-by: Erica Bugden <ebugden@efficios.com>

docs: fix: Update outdated term `target-byte-order`

`target-byte-order` was renamed to `native-byte-order` in commit
313a0bd9517a .

Change-Id: If72b59d810a989da9009d22d8c2b2ef7df72c495
Signed-off-by: Erica Bugden <ebugden@efficios.com>

fix: Update pyyaml to avoid build failures with cython 3

pyyaml 5.4 fails to build with Cython >= 3.0.0a10 on both Ubuntu jammy and
Debian 12, causing this project's build to fail with the following
error:

```
  Traceback (most recent call last):
    File "/tmp/tmp.b5DvVvhyNr/lib/python3.11/site-packages/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
      main()
    File "/tmp/tmp.b5DvVvhyNr/lib/python3.11/site-packages/pyproject_hooks/_in_process/_in_process.py", line 335, in main
      json_out['return_val'] = hook(**hook_input['kwargs'])
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/tmp/tmp.b5DvVvhyNr/lib/python3.11/site-packages/pyproject_hooks/_in_process/_in_process.py", line 118, in get_requires_for_build_wheel
      return hook(config_settings)
             ^^^^^^^^^^^^^^^^^^^^^
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/build_meta.py", line 341, in get_requires_for_build_wheel
      return self._get_build_requires(config_settings, requirements=['wheel'])
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/build_meta.py", line 323, in _get_build_requires
      self.run_setup()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/build_meta.py", line 338, in run_setup
      exec(code, locals())
    File "<string>", line 271, in <module>
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/__init__.py", line 107, in setup
      return distutils.core.setup(**attrs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/core.py", line 185, in setup
      return run_commands(dist)
             ^^^^^^^^^^^^^^^^^^
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/core.py", line 201, in run_commands
      dist.run_commands()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 969, in run_commands
      self.run_command(cmd)
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/dist.py", line 1234, in run_command
      super().run_command(command)
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/dist.py", line 988, in run_command
      cmd_obj.run()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/command/egg_info.py", line 314, in run
      self.find_sources()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/command/egg_info.py", line 322, in find_sources
      mm.run()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/command/egg_info.py", line 551, in run
      self.add_defaults()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/command/egg_info.py", line 589, in add_defaults
      sdist.add_defaults(self)
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/command/sdist.py", line 104, in add_defaults
      super().add_defaults()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/command/sdist.py", line 251, in add_defaults
      self._add_defaults_ext()
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/command/sdist.py", line 336, in _add_defaults_ext
      self.filelist.extend(build_ext.get_source_files())
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "<string>", line 201, in get_source_files
    File "/tmp/tmp9j5cmxoa/.venv/lib/python3.11/site-packages/setuptools/_distutils/cmd.py", line 107, in __getattr__
      raise AttributeError(attr)
  AttributeError: cython_sources
```

The upstream issue is https://github.com/yaml/pyyaml/issues/601 and
there are two possible solutions:

* Update pyyaml
* Constrain the version of cython

Change-Id: I2c7b8f33bcbc5c3a0a60578e2d0dd74cdca4f2ba
Signed-off-by: Kienan Stewart <kstewart@efficios.com>

tests: Verify build fails with mismatched byte order

This tests the byte order check added in the previous commit `Check that
native byte orders match at compilation`.

Change `byte-order-yes.yaml`:

This test configuration now defines the tracer byte order with
`native-byte-order: big-endian` (instead of
`trace-byte-order: big-endian`) so that this configuration can be used
both for the configuration tests and for the new byte order check test.
The `native-byte-order` property is used so that the C preprocessor
check will be present in the generated C code. The byte order is set to
`big-endian` so that building the generated C will fail on a
little-endian system.

This change does not reduce the test coverage because:
    a. `byte-order-yes.yaml` still tests that using one of the two byte
       order properties is a valid configuration, and
    b. The `trace-byte-order` property is tested via
       `trace-byte-order-big-endian.yaml` in the tracing tests.

Change-Id: Ic2aa7bdc7e56881233efe2e25153dc4e65ba309a
Signed-off-by: Erica Bugden <ebugden@efficios.com>

Check that native byte orders match at compilation

Context:

In barectf 3, the tracer's byte order is typically defined by the
'native-byte-order' property in the barectf yaml configuration.

When the tracer's configured native byte order does not match the
tracing target system's native byte order, it is not immediately obvious
that there is a problem. The generated tracer will build successfully
and, after integrating the tracer, tracing data will be generated.
However, if the user attempts to open the trace (e.g. with babeltrace),
it will fail. This is because the expected structure of the
trace data (described by the trace's metadata file) will not match the
actual structure of the generated trace data and so the trace reader
will not be able to parse the trace data. Because the issue only reveals
itself when reading the traces, it is challenging to identify it as a
tracer configuration error.

Changes:

When the tracer's byte order is defined by the 'native-byte-order'
property, add a byte order check at compilation time to prevent building
a little endian tracer for a big endian system (or vice versa). This
check is made at compilation time since the native byte order
(endianness) of the compilation target system can only be detected at
compilation time. This is the earliest moment it can be automatically
detected that the generated tracer has been misconfigured.

Implementation:

In barectf 3, there are currently two different properties that can be
used to configure the byte order of the generated traces:

    - 'native-byte-order': The recommended byte order property.
       Implemented via the 'TraceType' class.
    - 'trace-byte-order': Required for supporting barectf 2
       configuration files. Implemented via the
       'TraceTypeWithUnknownNativeByteOrder' class.

In 'barectf.c.j2', the byte order check should be performed when the
'native-byte-order' property is used, so the preprocessor checks are
included when the trace type class is 'TraceType'.

The byte order check is made using GCC common predefined macros. These
macros may not always be defined by the C compiler used to build the
barectf tracer, especially considering that barectf is designed for use
in embedded scenarios where tool chains are varied. In the case where
the byte order macros are not defined and the byte order cannot be
verified automatically, we choose not to warn the user because showing
a warning each time a barectf tracer is compiled could become
frustrating for users.

Test change:

Change 'tests/config/yaml/2/configs/pass/everything/config.yaml' to
little endian byte order (le) from big endian since otherwise the test
now fails.

    Note: The current barectf tests implicitly assume that the tests are
    run on a little endian system. All the tests under 'tests/tracing'
    will fail if run on a big endian system.

Change-Id: I3b084bb0084cf418371ef1ccec0d9f69ec26b814
Signed-off-by: Erica Bugden <ebugden@efficios.com>

tests: cleanup: Clarify test file does not exist

Change-Id: I8bff99e24ae7c25f1fb9fce3b4f3e616f839b2f6
Signed-off-by: Erica Bugden <ebugden@efficios.com>

tests: cleanup: Explain the purpose of some tests

Tests explained:
    * test_everything() (see note below)
    * `include` test cases

Identifying the intended purpose of the `include` test cases is a
partial prerequisite for the future work of checking that each
configuration test expecting a failure fails for the intended reason. At
the momment, we only check that configuration fails regardless of the
reason.

Note: test_everything() is a single stand alone test case that dates
back to from barectf 2 before the `tracing` tests existed. This is why
it checks more than just configuration generation. It is possibly
redundant with the more extensive tracing tests.

Change-Id: I59fe258b4f1eb7ef5c83f717f12973d38269adb4
Signed-off-by: Erica Bugden <ebugden@efficios.com>

tests: cleanup: Remove dead $include-replace tests

Context
-------

The $include-replace property appears to have been removed sometime in
the past. These 3 test cases are the only remaining references to this
property in the code base. The last reference to $include-replace in the
log is in commit 6839ffb (Use JSON schemas to validate the layout and
types of the YAML config) in `config_parse.py` at lines 2693-2694 where
the following comment referring to the property is removed:

    # In each object, only one of the $include and $include-replace
    # special properties is allowed.

All of this seems to point to this property no longer existing.

Changes
-------

Remove test cases referring to the $include-replace property.

Change-Id: I71d3293acf3518ebe5812db7fc9cc07ed933f64e
Signed-off-by: Erica Bugden <ebugden@efficios.com>

tests: fix: Run packet-set-buf tracing test

Context
-------

Currently, the packet-set-buf test is not run even though the test was
added as a regression test for a bug fix (0a5733a). The fix commit
message says:

    Adding a test with a custom platform calling
    barectf_packet_set_buf() with a `NULL` buffer after closing a
    completely full packet. Without this patch (in `barectf.c.j2`), this
    test leads to a segmentation fault.

It looks like this new test case was accidentally not added to the list
of valid test categories:

    * Sep 24, 2020 - Filter for valid test categories added (in 5b906ca)
    * Oct 6, 2020 - packet-set-buf test added, but not to valid
       categories (in 0a5733a)

Changes
-------

Add `packet-set-buf` to the valid test categories so the test will run.

Change-Id: I43a90bafe08897eaf107336fd8b629bad512b996
Signed-off-by: Erica Bugden <ebugden@efficios.com>

README.adoc: fix CI build badge

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I6644dae7b8b46444d28e609e8c15bccc5f7bac4e

barectf/cgen.py: add missing `Optional` type hint

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I8612fc834c371a3cc80ed7cfc94e2859261719b5

Fix: Handle barectf 2 configurations with any configured byte order

Context:

In barectf 2 (v2), the ‘byte-order’ property allows users to configure
the byte order with which traces are written (completely independently
of the traced architecture’s native byte order).

In barectf 3 (v3), the v2 property ‘byte-order’ was removed and the v3
property ‘native-byte-order’ is used instead. Currently, barectf 3
requires that the configured trace byte order match the byte order of
the traced architecture (i.e. the native byte order). This new
requirement promotes efficient tracing as it allows memcpy() to be used
for trace writing. Conversely, writing the trace in a different byte
order as the traced architecture requires at least one additional CPU
operation (byte swap) per written data point.

Issue:

Because of this use of memcpy() in trace writing (see implementation
section below), barectf 3 does not correctly handle barectf 2
configurations where the tracer's configured byte order does not match
the system's native byte order.

For example, consider a barectf 2 configuration file configured to
produce traces with a little-endian byte order
(byte-order: little-endian). If a barectf 3 tracer generated with this
configuration is used on a big-endian system, the traces produced will
appear corrupted.

Because the barectf 3 tracer copies data as-is with memcpy() (without
checking or swapping byte order), the byte order of the trace data
produced will not match the expected byte order (described in the
trace's metadata file) so the trace reader (e.g. babeltrace) will not be
able to read it.

Implementation:

The difference between barectf 2 (v2.3.1) and 3 byte order behavior:

 * barectf 2: Always uses the bt_bitfield_write functions when writing
    trace data.
 * barectf 3: Typically uses memcpy() when writing trace data (unless
    the data is not byte-aligned or has a length which is not a multiple
    of 8 bits)

In practice, the bt_bitfield_write functions are defined identically in
barectf 2 and barectf 3.

    Note: Although, barectf 2 does define the bt_bitfield_write
    functions with different type arguments depending on the configured
    byte order, in practice, these functions are _always_ called with
    the type unsigned char. So, there is no functional difference
    between how bt_bitfield_write_le and bt_bitfield_write_be are called
    regardless of the configured byte order. This means that we can get
    the same barectf 2 byte order behaviour in barectf 3 without
    adjusting the bt_bitfield_write functions based on the
    configuration.

Changes:

Handle barectf 2 configurations with any configured byte order by adding
an optional property ‘trace-byte-order’ (equivalent of the barectf 2
‘byte-order’ property). When this property is set, the tracer will
write the trace data in the configured byte order regardless of the
traced architecture’s native byte order (like barectf 2).

These changes are transparent for existing users of the barectf Python
library and no changes to their code are required.

The configuration property ‘trace-byte-order’ is implemented with a new
trace type class ‘TraceTypeWithUnknownNativeByteOrder’ both to avoid
breaking changes to the existing ‘TraceType’ class and to encourage use
of the ‘TraceType’ class over the new trace type.

The ‘trace-byte-order’ property is only intended to allow compatibility
with barectf 2 configurations. Because tracers configurated with
‘trace-byte-order’ will always use the bt_bitfield_write functions,
intentional use of this property in barectf 3 is unrecommended as it
could result in a less efficient tracer if the C compiler used is not
good at optimizing.

    Note: With a C compiler that optimizes well, the bt_bitfield_write
    functions will optimize down to either:
        a. 1 store instruction (equivalent to memcpy()), or
        b. 1 byte swap and 1 store (if the config byte order is
            different from the architecture’s native byte order).
    This raises the question: Why not just always use the
    bt_bitfield_write functions if they optimize so well and can be
    equivalent to a memcpy()? Because barectf is designed for use in
    embedded situations where toolchains are highly varied and it is not
    a given that the C compiler used is highly optimizing, it felt safer
    to still use memcpy() when the architecture and configured trace
    byte orders match as memcpy() is guaranteed to result in a quick
    write operation.

Testing:

Add the following test cases:

 * Configuration:
    * Fail if no byte order property is defined (byte-order-no.yaml)
    * Fail if both ‘native-byte-order’ and ‘trace-byte-order’ are
       defined (byte-order-yes-two-properties.yaml)
    * Pass if only ‘trace-byte-order’ is defined (byte-order-yes.yaml)
 * Tracing:
    * Barectf 2 configuration with ‘byte-order’ big endian (assuming a
       little endian test system) (trace-byte-order-big-endian.yaml)

The configuration test files are adapted from the effective
configuration generated from the barectf test config two-packets.yaml.

For the tracing test, the configuration was adapted from the barectf 2
wiki and the test source was adapted from the barectf test source
two-packets.c.

Philippe: Document the user-facing changes in `trace-type-obj.adoc`.

Change-Id: If0e17b537795a5093c406500706ca5d1fad051c6
Signed-off-by: Erica Bugden <ebugden@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests: Test passing configurations

Note: This is in preparation for adding additional passing
configurations. At the moment the only passing configuration is
config.yaml (tests/config/yaml/2/configs/pass/everything/config.yaml)
and this file is already tested via test_pass_everything.py.

Change-Id: I3a608bfb0d5cfcb1d48b42e21e060e80292e90b5
Signed-off-by: Erica Bugden <ebugden@efficios.com>

tests: Fix: Exclude test include YAML files from tests

These partial YAML files are included as part of other test cases and
are not intended to be run as separate tests.

The tests run based on these partial files were still listed as passing
because currently the test system only checks that a test fails
configuration, but does not compare the reason for that failure with an
expected reason. Since all the included files are invalid partial
configurations, configuration generation would necessarily fail, and so
the test would "pass".

Change-Id: Iaea53b6ff1fa184d284079befe695f22ad53ef09
Signed-off-by: Erica Bugden <ebugden@efficios.com>

tests: Make partial YAML files easy to filter

by giving them a specific file extension (inc.yaml).

Note: This is in preparation for filtering partial YAML files that are
not intended to be run as a separate test (e.g. because they will not
generate a valid configuration alone).

Change-Id: If6f0df7703e6e5df14bc53dbb3836819d6bf4568
Signed-off-by: Erica Bugden <ebugden@efficios.com>

pyproject.toml: require Python 3.8+

This fixes a dependency issue regarding Pylint (depending on a specific
version of astroid for Python 3.6, depending on wrapt 1.13 which makes
`poetry install` fail).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I987d2c6cb26647c261b270013449b4d8d3684fb7

Fix: Make traces with no data stream type ID readable by babeltrace

Currently, when the barectf configuration property
‘data-stream-type-id-field-type’ is false, barectf produces traces that
babeltrace (and Trace Compass) cannot parse.

To resolve this, remove all mentions of the data stream type ID from the
metadata file when there is no stream type ID field type feature.

Apparent cause:

When data stream type IDs are disabled, the barectf metadata file will
specify that the one data stream type has an ID of 0. This superfluous
information appears to be confusing to babeltrace even when the packet
header is explicitly empty (i.e. there is no mention of the stream type
ID in the actual trace data). This case falls into a grey area in the
CTF 1.8 specifcation (see below) and could arguably be a bug in
babeltrace since all the information needed to parse the trace
unambiguously is present in the metadata file. For example, the CTF
reader yactfr successfully reads such a trace. The stream type ID
information that barectf includes is superfluous, but not contradictory
of any data present in the trace.

However, add this fix because:
    a. Two common CTF trace format readers (babeltrace and
       Trace Compass) are unable to read these traces, and
    b. It is an easy fix in barectf.

CTF 1.8 specification:

This metadata issue is in a grey area of the CTF specification. The
specification says, “[The data stream type ID] field is optional if
there is only one [data stream type] in the metadata” and, “The [data
stream type ID] can be left out if there is only one [data stream type]
in the trace.” However, it does not say the data stream type ID _must_
be left out of the metadata if there is only one data stream type.

Implementation:

The condition added to the metadata Jinja template simply checks that
‘data-stream-type-id-field-type’ is not None. This works when
‘data-stream-type-id-field-type’ is set to false in the configuration,
because the data stream type ID field type will be set to None when the
trace type is created in config_parse_v3.py:

    dst_id_ft = self._feature_ft(...)

Testing:

The test does not check that babeltrace can read the trace, but it does
test that the lines mentioning the stream id are not present in the
generated metadata. Removing these lines has been manually verified to
be sufficient to allow babeltrace to read the trace.

The test source is adapted from the barectf test two-packets.c

Change-Id: I9de677440b98c41afe592d21a2ec18aa3c2e5bec
Signed-off-by: Erica Bugden <ebugden@efficios.com>

Fix: Invalid YAML test

In the original test, there was a space between '-' and '23' which is
invalid YAML syntax. However, this space was intentionally removed in
commit 688f203 (tests/config/fail/yaml/invalid.yaml: fix invalid YAML
(list/neg. value), May 2020)

It is not entirely clear what the intent of this test is, given the
space was intentionally removed, but it seems likely that the goal was
to test that when a YAML file contains invalid YAML syntax, the
configuration parsing will fail.

Without the space '-23', the test fails with this message:

Configuration: Cannot create configuration from YAML file
Configuration object:
`metadata` property:
`trace` property:
`byte-order` property: {'le': -23} is not of type 'string' (from schema
  `config/2/config`)

With the space '- 23', the test fails with this message:

Configuration: Cannot create configuration from YAML file
YAML loader: Cannot load file: sequence entries are not allowed here in
  "invalid.yaml", line 32, column 11

Replace space in '- 23' so that the test fails because of invalid YAML
syntax.

Change-Id: I262b5e664da0fbda820775eeaa3ac540f264b837
Signed-off-by: Erica Bugden <ebugden@efficios.com>

docs: clarify some sentences

Add information to reduce ambiguity and make it easier to search for
more details elsewhere if needed.

Change-Id: I0a54b701961dcb2e2225b843eb5d89499bd2a12d
Signed-off-by: Erica Bugden <ebugden@efficios.com>

docs: fix broken readme links

Change-Id: I5f069b84e365c61fd76c246231e0d937f8cc15c0
Signed-off-by: Erica Bugden <ebugden@efficios.com>

Fix: Pass C toolchain environments in tox.ini

CC is important if `cc' is not in PATH.

C_INCLUDE_PATH is important for the compiler to find the good headers,
e.g. <linux/limits.h>.

LIBRARY_PATH is important for the compiler to link against good
libraries, e.g. `crt1.o'.

This is mandatory for distributions that does not install
headers/libraries in standard locations that can be deduce by the
compiler, e.g. on Guix and NIX systems.

Note that this is intended for the C toolchain and not tests them self.
See https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html.

Change-Id: I35dca0a929b6ba00ba9fe7381a5d5bddce901da1
Signed-off-by: Olivier Dion <odion@efficios.com>

fix: add tox 4 support in tox.ini

Tox 4 introduced configuration syntax changes to tox.ini that requires
at least tox 3.18 for compatibility.

The 'passenv' configuration was documented as space separated in tox 3
and is now comma separated in tox 4. However, newline separated works in
both tox versions [1].

The 'whitelist_externals' configuration was replaced by
'allowlist_externals', the new value was introduced in 3.18 as an
alternative.

[1] https://tox.wiki/en/latest/upgrading.html#upgrading

Change-Id: Ibe6d16f7a180d4341f1a2c0f4a6343d72210cd94
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>

Fix: default value of `origin-is-unix-epoch` property is `true`

This is what the YAML clock type object documentation says and this was
indeed my intention.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I35f32a04755b46e304145313fbeed598a082d924

Fix: _process_trace_node_include(): `type` property is optional here

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ic0ce65189091fb892c6160256845701a51fa9863

Prepare for barectf v3.2.0

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Idcb27a5c81a08915278f4d12afb7ac4bdca3a836

barectf v3.1.0

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I3256dc44f7280489dc521e558828b61105691b55

pyproject.toml: require Jinja2 3.0+

This removes Jinja2 deprecation warnings at testing time (about
MarkupSafe).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I5652c21dc624a64d9aaee5c0b0f64744150562d9

barectf: add support for packet sequence number

Adds a new optional packet features object `sequence-number-field-type`,
which generates the metadata field type name `packet_seq_num` when
defined (defaults to false).

Currently this is conditionally maintained in `struct barectf_ctx` as a
`uint32_t` type like `events_discarded`.

In the future this could be improved to use the config type defined by
the stream in `struct barectf_default_ctx` so that the types are
aligned.

[Philippe Proulx: add documentation to Jon's patch.]

Refs: https://github.com/efficios/barectf/pull/24
Closes: https://github.com/efficios/barectf/issues/23
Signed-off-by: Jon Lamb <jon@auxon.io>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ibfa9e4ab73a7c338e41377aae01d498dee62086b

poetry.lock: update

This is needed to support Mypy on Python 3.10 as it uses
`typing_extensions` instead of `typed_ast` for Python ≥ 3.9 (`typed_ast`
seems broken on Python 3.10.2).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Use poetry-core build system

This allows building the project on a system without installing the full
poetry tooling and all its dependencies but only the minimal poetry-core
package while maintaining the current workflow for developers.

Introduced in poetry '1.1.0'.

Change-Id: I5be7e8d962f385cabb583666aeda8543f592ba66
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>

docs: yaml: dyn-array-ft-obj.adoc: fix wrong static array FT copy

Reported-by: Simon Marchi <simon.marchi@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: barectf_packet_set_buf(): keep full packet state

The condition of barectf_packet_is_full() is:

    ctx->at == ctx->packet_size

So we're reusing `ctx->at` to know whether or not a packet is full.

A full packet is always (already) closed.

The problem is that barectf_packet_set_buf() changes `ctx->packet_size`
without touching `ctx->at`. Therefore if the value of `ctx->packet_size`
changes, and if the packet was considered to be full, it's not the case
anymore, but it must be.

In barectf_packet_set_buf(), set `ctx->at` to `ctx->packet_size` if it
was already the case to keep any full packet state.

Adding a test with a custom platform calling barectf_packet_set_buf()
with a `NULL` buffer after closing a completely full packet. Without
this patch (in `barectf.c.j2`), this test leads to a segmentation fault.

Fixes: https://github.com/efficios/barectf/issues/18
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: {dst,trace-type}-obj.adoc: specify "default FT", not just "true"

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: build: index.adoc: add custom `stdint.h` example

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: platform: api.adoc: fix mistake

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Prepare for barectf v3.1.0

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf v3.0.0

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: how-barectf-works: update CTF trace structure images

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

test_pass_everything.py: check two new symbols

ed4a69c ("barectf.h.j2: add barectf_discarded_event_records_count()")
and 3bf37cb ("barectf.h.j2: add barectf_packet_buf_addr()") introduced
new API symbols to check here.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

test_pass_everything.py: use `cc` by default (like Make), not `gcc`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

test_pass_everything.py: reformat

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: whats-new.adoc: use headings for main topics

This is more readable than a single long list.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: cli: usage.adoc: improve page

Changes:

* Add link to <https://git-scm.com/>.

* Use the third person for the command descriptions in the
  General description section.

* Add and fix many internal links.

* Specify that `PREFIX` must be a valid C identifier.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing/conftest.py: add valid `basic-extra-pc-ft-members` cat.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add DST extra packet context FT members test

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add event record type tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add data stream type tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing/support/basic/test-platform.h: `ctx` -> `platform_ctx`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add data stream type event record feature tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add data stream type packet feature tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: `int main()` -> `int main(void)`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add trace type feature tests

This patch adds a new tracing test category named `counter-clock`.

This is because the `counter-clock` platform (in
`tests/tracing/support/counter-clock`) has a data stream clock which is
a simpler counter starting at 0.

The platform's base YAML trace type object,
`tests/tracing/support/counter-clock/base.yaml`, specifies a single
event record type `dummy` so that test-specific configurations which do
not need event record types are lighter.

The C files in `tests/tracing/src/counter-clock/trace-type-features`
do not call any tracing function: they only initialize and finalize
the test platform, which effectively opens and closes a single packet.

In the new `test-platform.c` file, test_platform_fini() closes the
current packet whether or not it's empty.

`tests/tracing/support/counter-clock/base-no-features.yaml` is a YAML
trace type object file which disables all the trace type and data stream
type features except the data stream type ID and event record type ID
features.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests: reflow licence headers for 72 columns

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: schemas/config/3/config.yaml: allow `uuid-field-type` to be `true`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf/schemas/config/3/config.yaml: `True` -> `true`

It works, but this is not Python.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf.c.j2: only declare `ts` variable when needed

This patch changes the `barectf.c.j2` template so that, for the
packet opening, packet closing, and event record header serialization
functions, the `ts` variable is only declared when it's used.

Without this patch, the C compiler can report such a warning:

    warning: unused variable ‘ts’ [-Wunused-variable]

In `barectf.c-macros.j2`, the open_close_func_preamble() macro is
changed to accept the timestamp packet feature in order to check either
the packet beginning or end timestamp field type feature.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: use test categories

This patch renames all `succeed` directories under `tests/tracing`
to `basic`. All tracing tests must succeed anyway.

In `basic/dynamic-array/of-double.yaml`:

* `basic` is the category.
* `dynamic-array` is the subcategory.
* `of-double.yaml` is the test file.

Support files are now per category: `tests/tracing/support` is moved
to `tests/tracing/support/basic`.

This makes it possible to add tracing test categories which have their
own platform and base YAML trace type object.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf: add pre-release version information (`barectf.__pre_version__`)

This makes it possible to make a `-dev` or `-pre` version for example.

`barectf.__version__` contains the pre-release information.

The generated metadata stream gets a new `tracer_pre` environment entry
set to this value (empty string as of this patch).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add basic structure data field tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add data stream test (two packets)

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: add basic int., enum., real, and string data field tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

configs/succeed/**/*.yaml: remove useless YAML document end

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: yaml: put static/dynamic array FT obj. C types example in partial

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: {static,dyn}-array-ft-obj.adoc: use example block

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Fix: YAML: force enumeration FT objects to have at least one mapping

As per CTF 1.8.3:

> Enumerations need to contain at least one entry.

Before this patch, ythose were legal:

    class: uenum
    size: 8

    class: uenum
    size: 8
    mappings: {}

    class: uenum
    size: 8
    mappings:
      A: []

CTF consumers would not like the resulting metadata stream. For
example, Babeltrace 2.1.0-rc1 [v1.2.0-3520-g73f74ae1f]:

    09-24 13:26:41.740 80492 80492 E PLUGIN/CTF/META/PARSER yyerror@parser.y:925 At line 109 in metadata stream: syntax error, unexpected CTF_RBRAC: token="}"
    09-24 13:26:41.740 80492 80492 E PLUGIN/CTF/META/DECODER ctf_metadata_decoder_append_content@decoder.c:280 [N/A] Cannot create the metadata AST out of the metadata text: mdec-addr=0x559dd9546a10
    09-24 13:26:41.740 80492 80492 W PLUGIN/SRC.CTF.FS/QUERY support_info_query@query.c:459 cannot append metadata content: metadata-decoder-status=-2
    09-24 13:26:41.741 80492 80492 W LIB/QUERY-EXECUTOR bt_query_executor_query@query-executor.c:231 Component class's "query" method failed: query-exec-addr=0x559dd9548070, cc-addr=0x559dd95233e0, cc-type=SOURCE, cc-name="fs", cc-partial-descr="Read CTF traces from the file sy", cc-is-frozen=0, cc-so-handle-addr=0x559dd9522770, cc-so-handle-path="lib/babeltrace2/plugins/babeltrace-plugin-ctf.so", object="babeltrace.support-info", params-addr=0x559dd9545f10, params-type=MAP, params-element-count=2, log-level=WARNING
    09-24 13:26:41.741 80492 80492 E CLI-CFG-SRC-AUTO-DISC support_info_query_all_sources@autodisc.c:493 babeltrace.support-info query failed.
    09-24 13:26:41.741 80492 80492 E CLI main@babeltrace2.c:2644 Command-line error: retcode=1

    ERROR:    [Babeltrace CLI] (babeltrace2.c:2644)
      Command-line error: retcode=1
    CAUSED BY [Source auto-discovery] (autodisc.c:493)
      babeltrace.support-info query failed.
    CAUSED BY [libbabeltrace2] (query-executor.c:231)
      Component class's "query" method failed: query-exec-addr=0x559dd9548070, cc-addr=0x559dd95233e0, cc-type=SOURCE, cc-name="fs", cc-partial-descr="Read CTF traces from
      the file sy", cc-is-frozen=0, cc-so-handle-addr=0x559dd9522770, cc-so-handle-path="babeltrace2/plugins/babeltrace-plugin-ctf.so",
      object="babeltrace.support-info", params-addr=0x559dd9545f10, params-type=MAP, params-element-count=2, log-level=WARNING

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf/templates: use `loop.last` instead of hack in `barectf/cgen.py`

This patch removes the raw text replacement at the end of
_CodeGen.gen_src() (`barectf/cgen.py`).

Instead, to avoid empty lines before `}`, Jinja 2 templates only
output an empty line it's not the loop's last iteration:

    {% if not loop.last %}{{ '\n' }}{% endif %}

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

test-platform.h: do not include `barectf.h`: forward-declare context

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

YAML files: remove empty line after `%YAML 1.2` directive

It's more common not to have one. At least the specification's
examples [1] do not have any.

[1]: https://yaml.org/spec/1.2/spec.html

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

tests/tracing: use a base trace type YAML file

This patch adds `tests/tracing/support/base.yaml` as a base YAML trace
type object for test configuration files to include.

`tests/tracing/conftest.py` is changed to add `tests/tracing/support` to
the barectf inclusion search directories and to only consider YAML files
in `tests/tracing/configs/succeed` (`tests/tracing/support/base.yaml` is
not a test).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: example.adoc: use file names as heading titles

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

modules/platform/pages/example.adoc: add a list of other examples

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs: add missing `build` module

This was not added because the root `.gitignore` file contained `build/`
(fixed by 4dd70d0 (".gitignore: simplify")).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

.gitignore: simplify

This patch removes lines from the root `.gitignore` file which were
useless for the barectf project.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

test-platform.c: write_packet(): use `const size_t`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

docs/modules/ROOT/pages/index.adoc: add internal links

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Document barectf 3

This patch adds the complete documentation of barectf 3 (upcoming major
release of the project).

The new `docs` directory is an Antora [1] documentation component
version. You can include it in an Antora site.

All the pages are written in AsciiDoc (Asciidoctor version).

Some contents were copied (and adapted) from the barectf wiki [2], but
most of the pages feature brand new text. The logo and diagrams are also
refreshed.

I'm removing the `barectf` CLI tool's manual page (`doc/man`) as it's
now documented in `docs/modules/cli/pages/usage.adoc`. Having the CLI
documented within the whole project's documentation makes it possible to
have critical links to and from other parts of it. This is to the
advantage of the reader.

[1]: https://antora.org/
[2]: https://github.com/efficios/barectf/wiki

barectf_platform_linux_fs_init(): accept DS file path, not trace dir.

This patch changes the Linux FS platform's
barectf_platform_linux_fs_init() function so that it accepts the data
stream file path instead of its trace directory.

This makes it possible to initialize many Linux FS platform contexts for
the same trace, each one targeting a distinct data stream file.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf-platform-linux-fs.c: write_packet(): use `const size_t`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf-platform-linux-fs.c: rename missing `ctx` -> `platform_ctx`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

poetry.lock: update

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

pyproject.toml: update description

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf/templates/c: name `void *` context parameters `vctx`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf.h.j2: add barectf_packet_buf_addr()

barectf_packet_buf_addr() is an alias of barectf_packet_buf().

This is more in line with the barectf_packet_set_buf() function which
sets both the buffer's address and size.

This change helps document the platform API.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf.h.j2: add barectf_discarded_event_records_count()

barectf_discarded_event_records_count() is an alias of
barectf_packet_events_discarded().

The count of discarded event records is not related to the current
packet; it's a data stream variable.

This change helps document the platform API.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf.h.j2: rename "clock callbacks" -> "clock source callbacks"

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf/templates/c: rename "back-end" -> "back end"

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Standardize root field type prefixes

This patch changes `cgen.py` and what depends on it so that:

* `_RootFtPrefixes` attribute names always begin with `P` (packet) or
  `ER` (event record).

* `_RootFtPrefixes` attribute values for event record prefixes do not
  begin with `er`.

  The C source context where this is used indicates that it's an event
  record field, so `er` is redundant.

  This also makes the documentation easier to understand.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Add missing `serialize-write-timestamp-statements.j2` file

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Enable discarded event records snapshot FT DST feature by default

This patch changes `config.py` (API) and the v3 YAML parser to make
the discarded event records snapshot field type (data stream type)
feature enabled by default.

This feature is nice to have, only adds an integer field to each packet,
and doesn't require anything from the user.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Rename "time" -> "timestamp" (terminology)

This patch renames the "time" concept to "timestamp" throughout.

The term "timestamp" is better to describe what used to be named "time",
for example a packet's beginning and end timestamps, and an event
record's timestamp.

"Time" has many definitions, one of which is duration, whereas the
only definition of "timestamp" in Antidote 10 is:

> a printed or stamped mark indicating a time or date of an event

which is pretty accurate.

Which is also why the timestamp members are named `timestamp_begin`,
`timestamp_end`, and `timestamp` in CTF 1.8.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Rename "target byte order" -> "native byte order"

Going back to the CTF terminology.

From the trace type's perspective, I believe this term is better. I
think it's also easier to understand when reading the documentation.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

config.py: move target byte order property from config. to trace type

This property is part of the trace type, as it's related to the byte
order of bit array field types which are all part of the trace type.

Also it's a CTF concept, not a barectf concept.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

poetry.lock: update

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

.gitignore: ignore generated HTML READMEs

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Use YAML 1.2 throughout

The `yes` and `no` boolean values do not exist in YAML 1.2 [1].

Change all of them for `true` and `false`.

Also, in `tests/tracing/configs` and in
`examples/linux-fs-simple/config.yaml`, add the explicit `%YAML 1.2`
directive to indicate that it's a YAML 1.2 document.

[1]: https://yaml.org/spec/1.2/spec.html#id2805071

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

Remove `CHANGELOG.md`

This is the change log of barectf 2.

For barectf 3, the change log will be part of the documentation.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf-tracepoint.h: improve quality

Changes:

* Reflow header comment to fit 72 columns.

* Capitalize comments.

* Use updated `barectf.h` definition names (`_BARECTF_IDENTIFIER_PREFIX`
  and `_BARECTF_DEFAULT_DATA_STREAM_TYPE_NAME`).

* Check for `BARECTF_TRACEPOINT_DATA_STREAM_TYPE_NAME` as an alternative
  to `BARECTF_TRACEPOINT_STREAM` (for consistency).

* Rework error messages.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

barectf.h.j2: use more accurate definition names

Leaving the old definitions to avoid breaking anything.

The updated names are:

`_BARECTF_PREFIX`:
    `_BARECTF_IDENTIFIER_PREFIX`

`_BARECTF_DEFAULT_STREAM`:
    `_BARECTF_DEFAULT_DATA_STREAM_TYPE_NAME`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

examples/linux-fs-simple: use `trace` as trace directory, not `ctf`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

examples/linux-fs-simple: convert README to Asciidoctor and improve it

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>