lib: make clock class precision optional

With the intent of supporting CTF 2, make the precision property of
clock classes optional under MIP 1.

 - Change the precision field of struct bt_clock_class to
   bt_property_uint.
 - Adjust lib-logging to omit the precision if not set.
 - Change bt_clock_class_create to make the precision property available
   with MIP 0, so that the precision will always be available with MIP
   0 (still with an initial value of 0).
 - Restrict bt_clock_class_get_precision to MIP 0.
 - Add bt_clock_class_get_opt_precision, which returns a
   bt_property_availability value.  Note that
   bt_clock_class_get_opt_precision can be used with MIP 0, it will
   always return BT_PROPERTY_AVAILABILITY_AVAILABLE.

Not done in this patch: adapt the Python bindings.

Philippe updated the documentation.

Change-Id: I1daf6627fda741f854d85ad6ff6f4ad132591662
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10710
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12724

diff --git a/include/babeltrace2/trace-ir/clock-class.h b/include/babeltrace2/trace-ir/clock-class.h
index 1222547bfaab29a35aaef0ee34d15fe2f11fbca1..8e9c818f444236518cea0adfbb510ed92d916ec0 100644 (file)
--- a/include/babeltrace2/trace-ir/clock-class.h
+++ b/include/babeltrace2/trace-ir/clock-class.h
@@ -208,7 +208,12 @@ A clock class has the following properties:
     Use bt_clock_class_set_offset() and bt_clock_class_get_offset().
   </dd>
 
-  <dt>\anchor api-tir-clock-cls-prop-precision Precision</dt>
+  <dt>
+    \anchor api-tir-clock-cls-prop-precision Precision
+    (optional when the clock class was created
+    from a \bt_comp which belongs to a trace processing \bt_graph
+    with the effective \bt_mip version&nbsp;1)
+  </dt>
   <dd>
     Precision of the clock class's instance (stream clocks) values
     (cycles).
@@ -218,7 +223,7 @@ A clock class has the following properties:
     anything between 35&nbsp;cycles and 49&nbsp;cycles.
 
     Use bt_clock_class_set_precision() and
-    bt_clock_class_get_precision().
+    bt_clock_class_get_opt_precision().
   </dd>
 
   <dt>
@@ -355,7 +360,17 @@ On success, the returned clock class has the following property values:
     <td>0&nbsp;cycles
   <tr>
     <td>\ref api-tir-clock-cls-prop-precision "Precision"
-    <td>0&nbsp;cycles
+    <td>
+      Depending on the effective \bt_mip (MIP) version of the trace
+      processing \bt_graph:
+
+      <dl>
+        <dt>MIP&nbsp;0</dt>
+        <dd>0&nbsp;cycles</dd>
+
+        <dt>MIP&nbsp;1</dt>
+        <dd>Unknown</dd>
+      </dl>
   <tr>
     <td>\ref api-tir-clock-cls-prop-origin "Origin"
     <td>Unix epoch
@@ -527,6 +542,14 @@ extern void bt_clock_class_set_precision(bt_clock_class *clock_class,
     Returns the precision (cycles) of the clock class
     \bt_p{clock_class}.
 
+@deprecated
+    Use bt_clock_class_get_opt_precision().
+
+@note
+    This function is only available when \bt_p{clock_class} was created
+    from a \bt_comp which belongs to a trace processing \bt_graph with
+    the effective \bt_mip (MIP) version&nbsp;0.
+
 See the \ref api-tir-clock-cls-prop-precision "precision" property.
 
 @param[in] clock_class
@@ -536,6 +559,7 @@ See the \ref api-tir-clock-cls-prop-precision "precision" property.
     Precision (cycles) of \bt_p{clock_class}.
 
 @bt_pre_not_null{clock_class}
+@bt_pre_clock_cls_with_mip{clock_class, 0}
 
 @sa bt_clock_class_set_precision() &mdash;
     Sets the precision of a clock class.
@@ -543,6 +567,38 @@ See the \ref api-tir-clock-cls-prop-precision "precision" property.
 extern uint64_t bt_clock_class_get_precision(
                const bt_clock_class *clock_class) __BT_NOEXCEPT;
 
+/*!
+@brief
+    Returns the precision of the clock class \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-precision "precision" property.
+
+@param[in] clock_class
+    Clock class of which to get the precision.
+@param[out] precision
+    @parblock
+    <strong>If this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*precision} is
+    the precision (cycles) of \bt_p{clock_class}.
+
+    Otherwise, the precision of \bt_p{clock_class} is unknown.
+    @endparblock
+
+@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
+    The precision of \bt_p{clock_class} is known.
+@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
+    The precision of \bt_p{clock_class} is unknown.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_not_null{precision}
+
+@sa bt_clock_class_set_precision() &mdash;
+    Sets the precision of a clock class.
+*/
+extern bt_property_availability bt_clock_class_get_opt_precision(
+               const struct bt_clock_class *clock_class,
+               uint64_t *precision) __BT_NOEXCEPT;
+
 /*!
 @brief
     Sets whether the \ref api-tir-clock-cls-origin "origin"

diff --git a/src/lib/lib-logging.c b/src/lib/lib-logging.c
index 2aafccedb8e9d948c1b795936c2fc6130125a15d..0e254e979210d4dc5d8887fbb25d81c18e2964da 100644 (file)
--- a/src/lib/lib-logging.c
+++ b/src/lib/lib-logging.c
@@ -923,14 +923,19 @@ static inline void format_clock_class(char **buf_ch, bool extended,
                BUF_APPEND_UUID(clock_class->uuid.value);
        }
 
-       BUF_APPEND(", %sis-frozen=%d, %sprecision=%" PRIu64 ", "
-               "%soffset-s=%" PRId64 ", "
+       BUF_APPEND(", %sis-frozen=%d", PRFIELD(clock_class->frozen));
+
+       if (clock_class->precision.base.avail) {
+               BUF_APPEND(", %sprecision=%" PRIu64,
+                       PRFIELD(clock_class->precision.value));
+       }
+
+       BUF_APPEND(", %soffset-s=%" PRId64 ", "
                "%soffset-cycles=%" PRIu64 ", "
                "%sorigin-namespace=%s, "
                "%sorigin-name=%s, "
                "%sorigin-uid=%s, "
                "%sbase-offset-ns=%" PRId64,
-               PRFIELD(clock_class->frozen), PRFIELD(clock_class->precision),
                PRFIELD(clock_class->offset_seconds),
                PRFIELD(clock_class->offset_cycles),
                PRFIELD(clock_class->origin.ns),

diff --git a/src/lib/trace-ir/clock-class.c b/src/lib/trace-ir/clock-class.c
index bb75fb9c13d0dce26a5d395042043239685c8866..7afc59b959fdc7ef986574a2f6804d7ec65a1cc0 100644 (file)
--- a/src/lib/trace-ir/clock-class.c
+++ b/src/lib/trace-ir/clock-class.c
@@ -142,6 +142,12 @@ struct bt_clock_class *bt_clock_class_create(bt_self_component *self_comp)
        }
 
        clock_class->frequency = UINT64_C(1000000000);
+
+       if (clock_class->mip_version == 0) {
+               clock_class->precision.base.avail =
+                       BT_PROPERTY_AVAILABILITY_AVAILABLE;
+       }
+
        set_origin_unix_epoch(clock_class);
        set_base_offset(clock_class);
        ret = bt_object_pool_initialize(&clock_class->cs_pool,
@@ -288,7 +294,23 @@ BT_EXPORT
 uint64_t bt_clock_class_get_precision(const struct bt_clock_class *clock_class)
 {
        BT_ASSERT_PRE_DEV_CLK_CLS_NON_NULL(clock_class);
-       return clock_class->precision;
+       BT_ASSERT_PRE_CC_MIP_VERSION_EQ(clock_class, 0);
+       BT_ASSERT_DBG(clock_class->precision.base.avail ==
+               BT_PROPERTY_AVAILABILITY_AVAILABLE);
+       return clock_class->precision.value;
+}
+
+BT_EXPORT
+bt_property_availability bt_clock_class_get_opt_precision(
+               const struct bt_clock_class *clock_class, uint64_t *precision)
+{
+       BT_ASSERT_PRE_NO_ERROR();
+       BT_ASSERT_PRE_DEV_CLK_CLS_NON_NULL(clock_class);
+       BT_ASSERT_PRE_DEV_NON_NULL("precision-output", precision,
+               "Precision (output)");
+
+       *precision = clock_class->precision.value;
+       return clock_class->precision.base.avail;
 }
 
 BT_EXPORT
@@ -300,7 +322,8 @@ void bt_clock_class_set_precision(struct bt_clock_class *clock_class,
        BT_ASSERT_PRE("valid-precision", precision != UINT64_C(-1),
                "Invalid precision: %![cc-]+K, new-precision=%" PRIu64,
                clock_class, precision);
-       clock_class->precision = precision;
+       clock_class->precision.value = precision;
+       clock_class->precision.base.avail = BT_PROPERTY_AVAILABILITY_AVAILABLE;
        BT_LIB_LOGD("Set clock class's precision: %!+K", clock_class);
 }
 

diff --git a/src/lib/trace-ir/clock-class.h b/src/lib/trace-ir/clock-class.h
index e4b88a1f7a466038b4d5a09e533b2e12505c567e..c1d71e308279672bb09a19304ba027dfa68bd4cd 100644 (file)
--- a/src/lib/trace-ir/clock-class.h
+++ b/src/lib/trace-ir/clock-class.h
@@ -12,6 +12,7 @@
 #include "lib/object.h"
 #include "common/common.h"
 #include "lib/object-pool.h"
+#include "lib/property.h"
 #include "common/uuid.h"
 #include <babeltrace2/types.h>
 #include "common/assert.h"
@@ -36,7 +37,7 @@ struct bt_clock_class {
        gchar *description;
 
        uint64_t frequency;
-       uint64_t precision;
+       struct bt_property_uint precision;
        int64_t offset_seconds;
        uint64_t offset_cycles;