barectf{nbsp}3 is a major update of the project.
-The main, user-visible changes are:
+This page presents the main, user-visible changes.
-* Support for user-defined
- xref:yaml:static-array-ft-obj.adoc[static] and
- xref:yaml:dyn-array-ft-obj.adoc[dynamic array field types].
+== Support for user-defined static and dynamic array field types
-* Reworked `barectf` Python API to match the recent CTF terminology and
- model (like https://babeltrace.org/[Babeltrace{nbsp}2] and the
+You can now use your own xref:yaml:static-array-ft-obj.adoc[static] and
+xref:yaml:dyn-array-ft-obj.adoc[dynamic array field types] within your
+xref:yaml:dst-obj.adoc[data stream type] or
+xref:yaml:ert-obj.adoc[event record type] root field types.
+
+====
+This xref:yaml:index.adoc[YAML configuration] has static and dynamic
+array field type objects:
+
+[source,yaml]
+----
+--- !<tag:barectf.org,2020/3/config>
+trace:
+ type:
+ $include:
+ - stdint.yaml
+ - stdmisc.yaml
+ native-byte-order: little-endian
+ data-stream-types:
+ my_stream:
+ event-record-common-context-field-type:
+ class: structure
+ members:
+ - src_ip_addr:
+ field-type:
+ class: static-array
+ length: 4
+ element-field-type: uint8
+ event-record-types:
+ my_event:
+ payload-field-type:
+ class: structure
+ members:
+ - message_id: uint32
+ - messages:
+ field-type:
+ class: dynamic-array
+ element-field-type: string
+----
+
+barectf generates the following
+C{nbsp}xref:tracing-funcs:index.adoc[tracing function] for the
+`my_event` event record type:
+
+[source,c]
+----
+void barectf_my_stream_trace_my_event(struct barectf_my_stream_ctx *sctx,
+ const uint8_t *cc_src_ip_addr,
+ uint32_t p_message_id,
+ uint32_t p___messages_len,
+ const char * const *p_messages);
+----
+====
+
+[[api]]
+== Reworked Python API
+
+The `barectf` Python API was revamped to:
+
+* Match the recent CTF terminology and model
+ (like https://babeltrace.org/[Babeltrace{nbsp}2] and the
upcoming CTF{nbsp}2).
-* Reworked xref:yaml:index.adoc[YAML configuration] format to match the
- new Python API.
+* Remove unneeded properties from some classes, like the encoding of an
+ integer field type object or the byte order of any field type object
+ (barectf{nbsp}3.0 always uses the configured native byte order).
+
+* Have a better object model.
++
+For example, a `barectf.SignedEnumerationFieldType` object is a
+`barectf.SignedIntegerFieldType` object, which is a
+`barectf._BitArrayFieldType` object, which is a
+`barectf._FieldType` object.
+
+* Decouple the xref:yaml:index.adoc#stages[effective YAML
+ configuration object] printing operation from the parsing operation.
++
+Now, `barectf.configuration_from_file()` returns a configuration object
+from a YAML configuration while `barectf.effective_configuration_file()`
+returns the effective version of a YAML configuration.
+
+* Make the `barectf.configuration_from_file()`,
+ `barectf.effective_configuration_file()`, and
+ `barectf.configuration_file_major_version()` functions accept a
+ https://docs.python.org/3/glossary.html#term-file-object[file object]
+ instead of a file system path.
++
+Those three functions can process barectf{nbsp}2 and{nbsp}<<yaml,3>>
+YAML configurations.
+
+* Offer all the API from the `barectf` package itself.
+
-barectf{nbsp}3 can still read and use barectf{nbsp}2 YAML
-configurations.
+From which modules are the names exactly is now an implementation
+detail: you only need to import `barectf`.
+
+NOTE: The `barectf` Python package's documentation is not available yet.
+
+[[yaml]]
+== New YAML configuration schema
+
+barectf{nbsp}3.0 comes with a new YAML configuration schema to
+parallel the <<api,new Python API>>.
+
+Rest assured that both the barectf Python API and the
+<<cli,`barectf` CLI tool>> can still process a
+barectf{nbsp}2 YAML configuration.
+
+The most significant changes are:
+
+* An updated terminology for property names and values.
+
+* The xref:yaml:cfg-obj.adoc[configuration object] mapping (the YAML
+ document) must be
+ xref:yaml:yaml-primer.adoc#tag[tagged] with
+ `tag:barectf.org,2020/3/config`:
+
-The main changes are:
+.Configuration object
+[source,yaml]
+----
+--- !<tag:barectf.org,2020/3/config>
+# ...
+----
+
-** Updated terminology for property names and values.
-** The xref:yaml:cfg-obj.adoc[configuration object] mapping (the YAML
- document) must be tagged with `tag:barectf.org,2020/3/config`.
-** The configuration object contains a xref:yaml:trace-obj.adoc[trace
- object] which contains a xref:yaml:trace-type-obj.adoc[trace type
- object].
+This is how barectf identifies a barectf{nbsp}3 YAML configuration.
++
+This YAML tag also makes it possible to insert a barectf configuration
+object within another, unrelated YAML document if need be.
+
+* The configuration object contains a xref:yaml:trace-obj.adoc[trace
+ object] which itself contains a xref:yaml:trace-type-obj.adoc[trace
+ type object]:
++
+.Configuration object
+[source,yaml]
+----
+--- !<tag:barectf.org,2020/3/config>
+trace:
+ type:
+ native-byte-order: big-endian
+ uuid: 296e1e04-91e4-4b54-b77c-19e776f1d3a7
+ # ...
+ environment:
+ sys_id: 1983
+ node_id: 17
+ sys_name: tel/long-can
+----
+
A trace can have an environment while a trace type can have a UUID.
-** You can specify two
- xref:yaml:cfg-obj.adoc#prefix-obj[prefixes] instead of a
- single one: a file name prefix and an identifier prefix.
+* You can specify _two_ independent
+ xref:yaml:cfg-obj.adoc#prefix-obj[prefixes] instead of a single one: a
+ file name prefix and an identifier prefix:
++
+.Configuration object
+[source,yaml]
+----
+--- !<tag:barectf.org,2020/3/config>
+options:
+ code-generation:
+ prefix:
+ file-name: my-system
+ identifier: msys_
+trace:
+ type:
+ # ...
+----
+
-With barectf{nbsp}2, the single prefix `my_app_` becomes the file name
-prefix `my_app` and the identifier prefix `my_app_`.
+With barectf{nbsp}2, the single prefix `my_app_` used to become the file
+name prefix `my_app` and the identifier prefix `my_app_`.
-** You don't need to specify special CTF structure field type members,
- like `magic`, `stream_id`, and `timestamp`.
+* You don't need to specify special CTF structure field type members,
+ like `magic`, `stream_id`, and `timestamp`.
++
+Instead, you specify xref:yaml:trace-type-obj.adoc#features-obj[trace
+type] and xref:yaml:dst-obj.adoc#features-obj[data stream type
+features]:
++
+.Trace type object
+[source,yaml]
+----
+$features:
+ magic-field-type: true
+ uuid-field-type: true
+data-stream-types:
+ my_stream:
+ $features:
+ packet:
+ beginning-timestamp-field-type: true
+ end-timestamp-field-type: false
+ discarded-event-records-counter-snapshot-field-type: true
+ event-record:
+ timestamp-field-type: true
+ # ...
+ # ...
+# ...
+----
++
+You can still control the exact field type of a feature:
+
-Instead, you specify
-xref:yaml:trace-type-obj.adoc#features-obj[trace type] and
-xref:yaml:dst-obj.adoc#features-obj[data stream type
-features]. You can still control the exact field type of a feature.
+.Trace type object
+[source,yaml]
+----
+$features:
+ data-stream-type-id-field-type: uint8
+# ...
+----
-** A data stream type can have zero or one
- xref:yaml:dst-obj.adoc#def-clk-type-name-prop[default clock type].
+* A data stream type can have zero or one
+ xref:yaml:dst-obj.adoc#def-clk-type-name-prop[default clock type]:
++
+.Trace type object
+[source,yaml]
+----
+clock-types:
+ sys23:
+ description: System clock (pin 23)
+ frequency: 8000000
+ origin-is-unix-epoch: false
+data-stream-types:
+ my_stream:
+ $default-clock-type-name: sys23
+ # ...
+ # ...
+# ...
+----
+
When a data stream type has a default clock type, its timestamp integer
field types (packet beginning, packet end, and event record)
automatically refer to this specific clock type, effectively removing
-the integer field type's `property-mappings` property.
+the xref:yaml:int-ft-obj.adoc[integer field type object]'s
+`property-mappings` property.
-** The only way to make a data stream type the default one is with its
- xref:yaml:dst-obj.adoc#is-def-prop[`$is-default`
- boolean property].
+* The only way to make a data stream type the default one is with its
+ xref:yaml:dst-obj.adoc#is-def-prop[`$is-default` boolean property].
++
+.Trace type object
+[source,yaml]
+----
+data-stream-types:
+ my_stream:
+ $is-default: true
+ # ...
+ # ...
+# ...
+----
-** You cannot specify custom
- xref:how-barectf-works:ctf-primer.adoc#pkt[packet] header and
- xref:how-barectf-works:ctf-primer.adoc#er[event record]
- header field type members anymore.
+* You cannot specify custom
+ xref:how-barectf-works:ctf-primer.adoc#pkt[packet] header and
+ xref:how-barectf-works:ctf-primer.adoc#er[event record] header field
+ type members anymore.
+
The header field types only exist for the trace format itself.
+
-Instead,
-xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[append user-defined
-members to the packet context field type]
-and use the
+Instead, xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[append
+user-defined members to the packet context field type] and use the
xref:yaml:dst-obj.adoc#er-common-ctx-ft-prop[event record common context
field type].
-** xref:yaml:trace-type-obj.adoc#ft-aliases-prop[Field type aliases]
- do not need to be defined in any specific order.
-** An xref:yaml:int-ft-obj.adoc[integer field type] _is_ a bit array
- field type.
+* You don't need to define
+ xref:yaml:trace-type-obj.adoc#ft-aliases-prop[field type aliases]
+ in any specific order:
++
+.Trace type object
+[source,yaml]
+----
+$field-type-aliases:
+ user-id:
+ $inherit: base-id
+ size: 16
+ base-id:
+ class: unsigned-integer
+ preferred-display-base: hexadecimal
+# ...
+----
++
+This is also the case within a barectf{nbsp}2 YAML metadata object.
+
+* An xref:yaml:int-ft-obj.adoc[integer field type] _is_ (conceptually
+ inherits) a bit array field type.
+
A bit array field type has size and alignment properties. It doesn't
have a byte order property: as of barectf{nbsp}3.0, the generated tracer
-always uses the native byte order.
-
-** An integer field type doesn't have a `signed` property: unsigned
- and signed integer field types are two different classes.
-** An xref:yaml:enum-ft-obj.adoc[enumeration field type] _is_ an integer
- field type.
-** The xref:yaml:enum-ft-obj.adoc#mappings-prop[mappings] of an
- enumeration field type are a YAML mapping of labels to sequences of
- integer ranges.
-** A xref:yaml:real-ft-obj.adoc[real field type] _is_ a bit array field
- type.
-** The xref:yaml:struct-ft-obj.adoc#members-prop[members] of a structure
- field type are a sequence instead of a mapping (YAML mappings are
- _not_ ordered).
+always uses the configured
+xref:yaml:trace-type-obj.adoc#native-bo-prop[native byte order].
+
+* An integer field type object doesn't have a `signed` property:
+ unsigned and signed integer field types are two different classes:
++
+.xref:yaml:struct-ft-obj.adoc[Structure field type object]
+[source,yaml]
+----
+class: structure
+members:
+ - unsigned_int:
+ field-type:
+ class: unsigned-integer
+ size: 32
+ - signed_int:
+ field-type:
+ class: signed-integer
+ size: 16
+----
+
+* An xref:yaml:enum-ft-obj.adoc[enumeration field type] _is_ an integer
+ field type; it doesn't have a `value-type` property anymore:
++
+.Signed enumeration field type object
+[source,yaml]
+----
+class: signed-enumeration
+size: 16
+alignment: 32
+preferred-display-base: octal
+# ...
+----
+
+* The xref:yaml:enum-ft-obj.adoc#mappings-prop[mappings] of an
+ enumeration field type are now a YAML mapping of labels to sequences
+ of integer ranges:
++
+.Signed enumeration field type object
+[source,yaml]
+----
+class: signed-enumeration
+size: 16
+mappings:
+ Poly:
+ - -23
+ - [45, 1001]
+ UdeM:
+ - [2000, 3000]
+ UQÀM:
+ - [1, 5]
+ - -40
+----
+
+* A xref:yaml:real-ft-obj.adoc[real field type] _is_ a bit array field
+ type. Its `size` property indicates if it's single-precision
+ or a double-precision:
++
+.Real field type object
+[source,yaml]
+----
+class: real
+size: 64
+----
+
+* The xref:yaml:struct-ft-obj.adoc#members-prop[members] of a structure
+ field type are a sequence instead of a mapping (YAML mappings are
+ _not_ ordered):
++
+.Structure field type object
+[source,yaml]
+----
+class: structure
+members:
+ - msg: string
+ - msg_id: uint8
+ - exceptions:
+ field-type:
+ class: dynamic-array
+ element-field-type: string
+----
+
This sequence is considered to be an _ordered mapping_, similar to
YAML's https://yaml.org/type/omap.html[`+!!omap+`] type.
-* Updated xref:yaml:include.adoc#std[standard partial YAML files] for
- the new YAML configuration format.
+The xref:yaml:include.adoc#std[standard partial YAML files] were updated
+to honour the new YAML configuration schema when a barectf{nbsp}3 YAML
+configuration includes them.
+
+[[cli]]
+== Upgraded command-line interface
+
+The xref:cli:usage.adoc[`barectf` CLI tool] now has a
+https://git-scm.com/[Git]-like user interface with the following commands
+
+xref:cli:usage.adoc#generate-command[`generate`]::
+ Exactly the barectf{nbsp}2 command-line interface: generates
+ the C{nbsp}source and CTF metadata stream files of a tracer
+ from a xref:yaml:index.adoc[YAML configuration file].
+
+xref:cli:usage.adoc#show-effective-configuration-command[`show-effective-configuration`]::
+ Prints the xref:yaml:index.adoc#stages[_effective_] version of
+ a YAML configuration file.
+
+xref:cli:usage.adoc#show-configuration-version-command[`show-configuration-version`]::
+ Prints the major version (2 or 3) of a YAML configuration file.
+
+The `barectf` CLI tool remains backward compatible with its
+barectf{nbsp}2 counterpart: the default command is `generate`.
-* The xref:cli:usage.adoc[`barectf` CLI tool] now has a Git-like user
- interface with a few commands.
+== Improved generated C{nbsp}code
+
+The generated C{nbsp}code is now ``const``-correct.
+
+There are a few new public definition and function aliases to match the
+<<api,Python API>>'s updated terminology:
+
+* `_BARECTF_IDENTIFIER_PREFIX` is defined to the same value as
+ `_BARECTF_PREFIX`.
+
-The `barectf` CLI tool remains backward compatible with barectf{nbsp}2's
-CLI: the default command is
-xref:cli:usage.adoc#generate-command[`generate`].
+See the code generation header options object's
+xref:yaml:cfg-obj.adoc#iden-prefix-def-prop[`identifier-prefix-definition`
+property].
+
+* `_BARECTF_DEFAULT_DATA_STREAM_TYPE_NAME` is defined to the same
+ value as `_BARECTF_DEFAULT_STREAM`.
++
+See the code generation header options object's
+xref:yaml:cfg-obj.adoc#def-dst-name-def-prop[`default-data-stream-type-name-definition`
+property].
+
+* xref:platform:api.adoc#barectf-disc-er-count-func[`+barectf_discarded_event_records_count()+`]
+ returns the same thing as `+barectf_packet_events_discarded()+`.
+
+* xref:platform:api.adoc#barectf-pkt-buf-addr-func[`+barectf_packet_buf_addr()+`]
+ returns the same thing as `+barectf_packet_buf()+`.
-* The generated C{nbsp}code is ``const``-correct.
+The `barectf-bitfield.h` header only contains what's needed by the
+target's xref:yaml:trace-type-obj.adoc#native-bo-prop[native byte
+order]. Also, only `barectf.c` includes this header now, not leaking its
+definitions through the public `barectf.h` header.
projects / barectf.git / commitdiff
