Add MIP 1 support to your component class

Babeltrace 2.1 introduces new trace IR features under the new version 1 of the Message Interchange Protocol (MIP).

This guide shows the differences between MIP 0 and MIP 1 along with how to update your component class, which already supports MIP 0, to also support MIP 1.

Implement the "get supported MIP versions" method

Even though you could implement the "get supported MIP versions" component class method in Babeltrace 2.0, you didn't have to because without it, the default supported MIP version is 0, which was the only available one anyway.

Starting from Babeltrace 2.1, your component may support MIP 0, MIP 1, or both. It's now mandatory to implement the "get supported MIP versions" method to support MIP 1 as the bt_graph_add_source_component_with_initialize_method_data(), bt_graph_add_filter_component_with_initialize_method_data(), and bt_graph_add_sink_component_with_initialize_method_data() functions have the following precondition:

Precondition

The "get supported MIP versions" method of component_class, given the same params, initialize_method_data, and logging_level parameters, makes one of its supported Message Interchange Protocol (MIP) version ranges contain the effective MIP version of graph (see bt_graph_create()).

To make your component indicate MIP 1 support:

1. In your plugin definition C file, use the BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(), BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(), or BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD() macro to set the "get supported MIP versions" method of your component class.

   For example:

   BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(meow,
       meow_get_supported_mip_versions);

2. In your "get supported MIP versions" method, include version 1 in the supported version range.

   For example, to show support for both MIP 0 and MIP 1:

   bt_component_class_get_supported_mip_versions_method_status
   meow_get_supported_mip_versions(
       bt_self_component_class_sink * const self_component_class,
       const bt_value * const params, void * const initialize_method_data,
       const bt_logging_level logging_level,
       bt_integer_range_set_unsigned * const supported_versions)
   {
       if (bt_integer_range_set_unsigned_add_range(supported_versions, 0, 1) !=
                BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK) {
            return BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR;
       }
    
       return BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK;
   }

   You may rely on params and initialize_method_data to determine the exact MIP versions your component class instances expect to support.

Get the effective MIP version

Although most API functions work identically with both MIP 0 and MIP 1, some of them are only valid for a specific MIP version.

In a component or message iterator method, especially if your component supports both available versions of the MIP, you might need to decide which API function to use at run time depending on the current, effective MIP version of the trace processing graph.

The available MIP version access functions are:

• bt_clock_class_get_graph_mip_version()
• bt_field_class_get_graph_mip_version()
• bt_self_component_get_graph_mip_version()
• bt_self_message_iterator_get_graph_mip_version()
• bt_trace_class_get_graph_mip_version()

For example, in a sink component printing the details of a trace, you may only get its namespace under MIP 1:

if (bt_self_component_get_graph_mip_version(self_component) == 1) {
    print_opt_string_property("Namespace", bt_trace_get_namespace(the_trace));
} else {
    print_none_property("Namespace");
}

Changes

MIP 1 brings the required changes to support the features of CTF 2. As such:

• Clock class, event class, stream class, and trace objects may have a namespace, a name, and a unique ID (UID).

  The UUID property of clock class and trace objects is removed in favor of the new UID property.

• Important parts of the clock class API are changed.
• A bit array field class may have flags.
• An integer field class may have field value hints.
• There are new BLOB field classes and fields.
• The field location system replaces the field path one.

The following subsections provide details about the changes above and how MIP 0 translates to MIP 1 in their context.

Namespace, name, and unique ID

The clock class, event class, stream class, and trace objects may have a namespace, a name, and a unique ID (UID).

Together, we call those three optional properties the identity of an object.

Babeltrace 2 doesn't specify what's the purpose of an identity and why you should use it, except for clock classes: it exists to accomodate trace formats.

On creation, an object has no identity (the values of the namespace, name, and UID properties are missing).

For clock class and trace objects, MIP 1 removes the UUID property in favor of those new properties. In other words, you cannot use the following functions with MIP 1:

• bt_clock_class_set_uuid()
• bt_clock_class_get_uuid()
• bt_trace_set_uuid()
• bt_trace_get_uuid()

A good strategy is to set the UID property to the textual representation of the UUID instead.

The new identity property access functions are:

Object	Namespace access	Name access (also valid with MIP 0)	UID access
Clock class	bt_clock_class_set_namespace() bt_clock_class_get_namespace()	bt_clock_class_set_name() bt_clock_class_get_name()	bt_clock_class_set_uid() bt_clock_class_get_uid()
Event class	bt_event_class_set_namespace() bt_event_class_get_namespace()	bt_event_class_set_name() bt_event_class_get_name()	bt_event_class_set_uid() bt_event_class_get_uid()
Stream class	bt_stream_class_set_namespace() bt_stream_class_get_namespace()	bt_stream_class_set_name() bt_stream_class_get_name()	bt_stream_class_set_uid() bt_stream_class_get_uid()
Trace	bt_trace_set_namespace() bt_trace_get_namespace()	bt_trace_set_name() bt_trace_get_name()	bt_trace_set_uid() bt_trace_get_uid()

Clock class API

The clock class API is changed as such from MIP 0 to MIP 1:

• The identity is the namespace, name, and UID tuple instead of the name and UUID pair.

  See the Namespace, name, and unique ID section above.

• The precision property is optional.

  bt_clock_class_create() makes the initial precision unknown.

  Use the new bt_clock_class_get_opt_precision() function to get whether or not the precision is known and, if it's known, its value.

  bt_clock_class_get_precision() is not available and becomes deprecated.

• There's a new, optional accuracy property.

  The accuracy value is in clock cycles.

  While the precision property describes the random errors of clocks, the accuracy property describes systematic errors. From Accuracy and precision:

  • Accuracy is how close a given set of measurements (observations or readings) are to their true value.
  • Precision is how close the measurements are to each other.

  bt_clock_class_create() makes the initial accuracy unknown.

  Use the new bt_clock_class_set_accuracy() and bt_clock_class_get_accuracy() functions.

  Having an unknown accuracy makes it possible to set the intended origin of a clock class while communicating that clock snapshots may not align with the true origin.

• The origin property of a clock class, which is either unknown or the Unix epoch with MIP 0, can be custom.

  A custom origin is a point on the real timeline which is the base of clock snapshots. The Unix epoch is just a renowned origin with its own dedicated functions in Babeltrace 2.

  Snapshots of clocks having the same origin, whatever the other clock class properties, have a correlation.

  A custom origin is identified by an optional namespace and a mandatory name/UID pair. Set the custom origin of a clock class with bt_clock_class_set_origin().

  Make the origin the Unix epoch with bt_clock_class_set_origin_unix_epoch() or unknown with bt_clock_class_set_origin_unknown().

  bt_clock_class_set_origin_is_unix_epoch() still works but is deprecated.

  The clock class origin property getters are:

  • bt_clock_class_get_origin_namespace()
  • bt_clock_class_get_origin_name()
  • bt_clock_class_get_origin_uid()
  • bt_clock_class_origin_is_known() (also valid with MIP 0)
  • bt_clock_class_origin_is_unix_epoch() (also valid with MIP 0)

  bt_clock_class_create() still sets the initial origin to the Unix epoch.

Bit array field class flags

A bit array field class may have zero or more flags.

The bit array field class flag API is very similar to the unsigned enumeration field class mapping API.

A flag assigns a label to one or more bits, by indexes, of instances (bit array fields). When any of the bits of some flag is set (true) within a bit array field, said flag is known to be active.

The new related functions are:

Add a flag to a bit array field class

bt_field_class_bit_array_add_flag()

Get the number of flags in a bit array field class

bt_field_class_bit_array_get_flag_count()

Borrow a flag from a bit array field class

• bt_field_class_bit_array_borrow_flag_by_index_const()
• bt_field_class_bit_array_borrow_flag_by_label_const()

Get the label of a bit array field class flag

bt_field_class_bit_array_flag_get_label()

Borrow the bit index range set of a bit array field class flag

bt_field_class_bit_array_flag_borrow_index_ranges_const()

Get the labels of all the active flags of a bit array field class for the set bits of some integral value

bt_field_class_bit_array_get_active_flag_labels_for_value_as_integer()

Get the labels of all the active flags of the class of a bit array field for the set bits of its integral value

bt_field_bit_array_get_active_flag_labels()

Integer field class field value hints

An integer field class may have field value hints.

An integer field class field value hint is a marker that provides additional context about the expected characteristics of instance (integer field) values. These hints serve as non-binding recommendations to guide downstream components about specific properties or optimizations.

As of Babeltrace 2.0, the only available hint is BT_FIELD_CLASS_INTEGER_FIELD_VALUE_HINT_SMALL which means that instances of the integer field class are expected to hold small integer values.

The new related functions are:

Set the field value hints of an integer field class

bt_field_class_integer_set_field_value_hints()

Get the field value hints of an integer field class

bt_field_class_integer_get_field_value_hints()

Get whether or not an integer field class has a given field value hint

bt_field_class_integer_has_field_value_hint()

BLOB field classes and fields

A BLOB field class describes BLOB fields which contain zero or more bytes of binary data.

With MIP 0, you can use a string field class or an array field class with an 8-bit unsigned integer element field class as the class of some byte container. However, both have their limitations.

A BLOB field is the perfect container of pure binary data.

Like static and dynamic array field classes, you can create both static and dynamic BLOB field classes:

bt_field_class_blob_static_create()

Is a BT_FIELD_CLASS_TYPE_BLOB and a BT_FIELD_CLASS_TYPE_STATIC_BLOB.

bt_field_class_blob_dynamic_without_length_field_location_create()

Is a BT_FIELD_CLASS_TYPE_BLOB, a BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB, and a BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITHOUT_LENGTH_FIELD.

bt_field_class_blob_dynamic_with_length_field_location_create()

Is a BT_FIELD_CLASS_TYPE_BLOB, a BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB, and a BT_FIELD_CLASS_TYPE_DYNAMIC_BLOB_WITH_LENGTH_FIELD.

This one accepts a field location: see the Field location API section below to learn more.

A BLOB field class has a media type property which the creation functions initialize to application/octet-stream, a very generic one. The media type indicates which kind of data the instances hold.

Just like with a dynamic array field, set the length of a dynamic BLOB field with bt_field_blob_dynamic_set_length() before getting its internal buffer.

Get the length of a BLOB field with bt_field_blob_get_length().

Get the internal buffer of a BLOB field with:

Write mode

bt_field_blob_get_data()

Read mode

bt_field_blob_get_data_const()

Field location API

Starting from MIP 1, the classes of all the fields with links to other fields use a field location to show the link instead of a field path.

A field location is different from a field path: it contains a list of structure field member names to follow from some root scope to reach the target field. This makes it possible, for example, for the length field of some dynamic field to be located within one or more distant option fields and/or variant fields.

See Field location procedure to learn the exact procedure to locate a field.

Whereas libbabeltrace2 creates field path objects for you when you provide the target field class at dependent field class creation time, you create a field location object yourself. This is because a dependent field class may target more than one field class.

The field location API is:

Create a field location

bt_field_location_create()

You provide the root scope and all the items (structure member names) to this function.

Get the root scope of a field location

bt_field_location_get_root_scope()

Get an item by index from a field location

bt_field_location_get_item_count()

Reference count

• bt_field_location_get_ref()
• bt_field_location_put_ref()
• BT_FIELD_LOCATION_PUT_REF_AND_RESET()
• BT_FIELD_LOCATION_MOVE_REF()

The new field class creation functions to use are:

MIP 0 function	MIP 1 function
N/A	bt_field_class_blob_dynamic_without_length_field_location_create()
N/A	bt_field_class_blob_dynamic_with_length_field_location_create()
bt_field_class_array_dynamic_create() with the length_field_class parameter set to NULL	bt_field_class_blob_dynamic_without_length_field_location_create()
bt_field_class_array_dynamic_create() with the length_field_class parameter not set to an unsigned integer field class	bt_field_class_array_dynamic_with_length_field_location_create()
bt_field_class_option_without_selector_create()	bt_field_class_option_without_selector_field_location_create()
bt_field_class_option_with_selector_field_bool_create()	bt_field_class_option_with_selector_field_location_bool_create()
bt_field_class_option_with_selector_field_integer_unsigned_create()	bt_field_class_option_with_selector_field_location_integer_unsigned_create()
bt_field_class_option_with_selector_field_integer_signed_create()	bt_field_class_option_with_selector_field_location_integer_signed_create()
bt_field_class_variant_create() with the selector_field_class parameter set to NULL	bt_field_class_variant_without_selector_field_location_create()
bt_field_class_variant_create() with the selector_field_class parameter set to an unsigned integer field class	bt_field_class_variant_with_selector_field_location_integer_unsigned_create()
bt_field_class_variant_create() with the selector_field_class parameter set to a signed integer field class	bt_field_class_variant_with_selector_field_location_integer_signed_create()

The new field location borrowing functions are:

• bt_field_class_blob_dynamic_with_length_field_borrow_length_field_location_const()
• bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const()
• bt_field_class_option_with_selector_field_borrow_selector_field_location_const()
• bt_field_class_variant_with_selector_field_borrow_selector_field_location_const()

The following functions aren't available with MIP 1:

• All the field path API functions
• bt_field_class_array_dynamic_create()
• bt_field_class_option_without_selector_create()
• bt_field_class_option_with_selector_field_bool_create()
• bt_field_class_option_with_selector_field_integer_unsigned_create()
• bt_field_class_option_with_selector_field_integer_signed_create()
• bt_field_class_variant_create()
• bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
• bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
• bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()