`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"
f9d5d8b...
by
Kienan Stewart <email address hidden>
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
```
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.
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.
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.
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.
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.
