config: replace trace type's default BO with configuration's target BO
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Fri, 4 Sep 2020 01:06:03 +0000 (21:06 -0400)
committerPhilippe Proulx <eeppeliteloop@gmail.com>
Fri, 4 Sep 2020 01:06:03 +0000 (21:06 -0400)
commit7fffc7d16d383d900f79f3632ebbccb2a2a7ff9e
treeae99161c9d7bd4d604f3288bb37fa082eb9edb17
parent3fe7471a985bab5a3bb111f5dfa3880a78feef22
config: replace trace type's default BO with configuration's target BO

This patch removes the `default_byte_order` property from the
`barectf.TraceType` class.

Instead of having this helper, a configuration now has a mandatory
`target_byte_order` property.

Because of the trace type's default byte order role in
`barectf-bitfield.h`, it's more fundamental than a mere "default": it's
actually the byte order you expect the target system to have. In other
words, you could not make the trace type's default byte order big-endian
to when your target system is a little-endian machine: the bit array
serialization process will fail at tracing time. Therefore I found that
the "default byte order" term was misleading.

This change brings a challenge, however: when you don't specify a group
of stream type or trace type features, or when you specify
`barectf.DEFAULT_FIELD_TYPE` for a given feature field type, which byte
order should the automatically created integer field type(s) have?

My solution is to add an optional default byte order parameter to each
constructor which _could_ create an integer field type (recursively). As
soon as this is going to happen, the default byte order must not be
`None`. For example, when you create a `barectf.StreamTypeEventFeatures`
object, you can use `barectf.DEFAULT_FIELD_TYPE`, but you must also pass
a default byte order:

    features = barectf.StreamTypeEventFeatures(barectf.DEFAULT_FIELD_TYPE,
                                               default_byte_order=barectf.ByteOrder.LITTLE_ENDIAN)

This can also be when you create a stream type or a trace type, as if
you don't pass any feature object, then the constructor creates one for
you, which eventually creates default field types. For example:

    trace_type = barectf.TraceType(my_stream_types,
                                   default_byte_order=barectf.ByteOrder.BIG_ENDIAN)

This design is not super elegant, but it's a compromise for the
constructors to have everything they need to create full integer field
types. This is also why the `byte_order` property of a bit array field
type is now mandatory; there's no (peculiar) temporary state where it
remains `None` until the complete trace type exists.

I thought about making the target byte order little-endian by default,
for example, but considering that barectf is used to generate tracers
for embedded and bare-metal systems, I found that solution too
indiscriminate.

In a barectf 3 YAML configuration file:

* The trace type's `$default-byte-order` is removed.

* There's a new, mandatory `target-byte-order` configuration property.

* You can still not specify any bit array field type byte order: the
  parser uses the configuration's target byte order in that case.

A barectf 2 YAML trace type's `byte-order` property (which is already
mandatory) is copied as the v3 configuration node's `target-byte-order`
property.

`bitfield.h.j2` and `metadata.j2` are changed to use the configuration's
target byte order instead of the trace type's default byte order.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
barectf/config.py
barectf/config_parse_v2.py
barectf/config_parse_v3.py
barectf/schemas/config/3/config.yaml
barectf/templates/c/bitfield.h.j2
barectf/templates/metadata/metadata.j2
This page took 0.023649 seconds and 4 git commands to generate.