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>

.gitreview: set branch to stable-3.1

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

README.adoc: fix CI build badge

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

Prepare for barectf v3.1.3

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

barectf v3.1.2

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

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>

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>

pyproject.toml: require Pylint 2.13+ and Python 3.6.2+

Doing so solves Poetry errors about incompatible dependencies: Pylint
2.13 requires Python 3.6.2+, while Pylint 2.14 requires Python 3.7.2+.

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

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>
(cherry picked from commit 3dca662da1619d2cb4e0f1eea3caf160b785d2df)

docs: fix broken readme links

Change-Id: I5f069b84e365c61fd76c246231e0d937f8cc15c0
Signed-off-by: Erica Bugden <ebugden@efficios.com>
(cherry picked from commit f4dfde3991eecf63b4f772deb041597cf7b1ff63)
(cherry picked from commit f16a7f21934027d49e8363295e0f0c67e112ccce)

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>
(cherry picked from commit 5a496a3d8f385ba3b427d2209509653fa847818f)

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>
(cherry picked from commit c4c460634f3e5980f97b04157ba96b3c615af574)

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

Prepare for barectf v3.1.2

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

barectf v3.1.1

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

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.1.1

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

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>

linux-fs-simple/config.yaml: convert to v3 format

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

linux-fs-simple.c: improve quality

Changes:

* Remove unneeded included headers.
* Remove unneeded TO_VOID_PTR() macro.
* Use `const` where possible.
* Use single return points.
* Capitalize comments.

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

linux-fs-simple/Makefile: remove nonexistent `view` from `.PHONY`

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

barectf-platform-linux-fs.c: improve quality

Changes:

* Remove unneeded included headers.
* Remove unneeded TO_VOID_PTR() macro.
* Use `const` where possible.
* Use single return points.
* Rename platform context variables to `platform_ctx`.
* Capitalize comments.

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

barectf-platform-linux-fs.*: remove header titles

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