From: Simon Marchi <simon.marchi@efficios.com>
Date: Fri, 1 Sep 2023 19:37:38 +0000 (-0400)
Subject: lib: add clock class accuracy property
X-Git-Url: http://drtracing.org/?a=commitdiff_plain;h=85f6ebeb602b158fb858862850f79eda00a69046;p=babeltrace.git

lib: add clock class accuracy property

With the intent of supporting CTF 2, add the accuracy property to clock
classes.

 - Add the bt_clock_class_{g,s}et_accuracy getter and setter, both of
   which are restricted to MIP >= 1.
 - Add the accuracy field to struct bt_clock_class.
 - Make lib-logging print the accuracy of a clock class, if set.

Philippe updated the documentation.

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

diff --git a/include/babeltrace2/trace-ir/clock-class.h b/include/babeltrace2/trace-ir/clock-class.h
index 8e9c818f..a510ab62 100644
--- a/include/babeltrace2/trace-ir/clock-class.h
+++ b/include/babeltrace2/trace-ir/clock-class.h
@@ -218,7 +218,9 @@ A clock class has the following properties:
     Precision of the clock class's instance (stream clocks) values
     (cycles).
 
-    For example, considering a precision of 7&nbsp;cycles and the stream
+    For example, considering a precision of 7&nbsp;cycles, an
+    \link api-tir-clock-cls-prop-accuracy accuracy\endlink
+    of 0&nbsp;cycles, and the stream
     clock value 42&nbsp;cycles, the real stream clock value can be
     anything between 35&nbsp;cycles and 49&nbsp;cycles.
 
@@ -226,6 +228,27 @@ A clock class has the following properties:
     bt_clock_class_get_opt_precision().
   </dd>
 
+  <dt>
+    \anchor api-tir-clock-cls-prop-accuracy
+    \bt_dt_opt Accuracy
+    (only available 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>
+    Accuracy of the clock class's instance (stream clocks) values
+    (cycles).
+
+    For example, considering an accuracy of 7&nbsp;cycles, a
+    \link api-tir-clock-cls-prop-precision precision\endlink
+    of 0&nbsp;cycles, and the stream
+    clock value 42&nbsp;cycles, the real stream clock value can be
+    anything between 35&nbsp;cycles and 49&nbsp;cycles.
+
+    Use bt_clock_class_set_accuracy() and
+    bt_clock_class_get_accuracy().
+  </dd>
+
   <dt>
     \anchor api-tir-clock-cls-prop-origin
     Origin
@@ -371,6 +394,11 @@ On success, the returned clock class has the following property values:
         <dt>MIP&nbsp;1</dt>
         <dd>Unknown</dd>
       </dl>
+  <tr>
+    <td>
+      \bt_mip version&nbsp;1:
+      \ref api-tir-stream-cls-prop-accuracy "accuracy"
+    <td>Unknown
   <tr>
     <td>\ref api-tir-clock-cls-prop-origin "Origin"
     <td>Unix epoch
@@ -599,6 +627,60 @@ extern bt_property_availability bt_clock_class_get_opt_precision(
 		const struct bt_clock_class *clock_class,
 		uint64_t *precision) __BT_NOEXCEPT;
 
+/*!
+@brief
+    Sets the accuracy (cycles) of the clock class \bt_p{clock_class} to
+    \bt_p{accuracy}.
+
+See the \ref api-tir-clock-cls-prop-accuracy "accuracy" property.
+
+@param[in] clock_class
+    Clock class of which to set the accuracy to \bt_p{accuracy}.
+@param[in] accuracy
+    New accuracy of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@bt_pre_clock_cls_with_mip{clock_class, 1}
+
+@sa bt_clock_class_get_accuracy() &mdash;
+    Returns the accuracy of a clock class.
+*/
+extern void bt_clock_class_set_accuracy(bt_clock_class *clock_class,
+		uint64_t accuracy) __BT_NOEXCEPT;
+
+/*!
+@brief
+    Returns the accuracy of the clock class \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-accuracy "accuracy" property.
+
+@param[in] clock_class
+    Clock class of which to get the accuracy.
+@param[out] accuracy
+    @parblock
+    <strong>If this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*accuracy} is
+    the accuracy (cycles) of \bt_p{clock_class}.
+
+    Otherwise, the accuracy of \bt_p{clock_class} is unknown.
+    @endparblock
+
+@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
+    The accuracy of \bt_p{clock_class} is known.
+@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
+    The accuracy of \bt_p{clock_class} is unknown.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_not_null{accuracy}
+
+@sa bt_clock_class_set_accuracy() &mdash;
+    Sets the accuracy of a clock class.
+*/
+extern bt_property_availability bt_clock_class_get_accuracy(
+		const struct bt_clock_class *clock_class,
+		uint64_t *accuracy) __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 0e254e97..fba67714 100644
--- a/src/lib/lib-logging.c
+++ b/src/lib/lib-logging.c
@@ -930,6 +930,11 @@ static inline void format_clock_class(char **buf_ch, bool extended,
 			PRFIELD(clock_class->precision.value));
 	}
 
+	if (clock_class->accuracy.base.avail) {
+		BUF_APPEND(", %saccuracy=%" PRIu64,
+			PRFIELD(clock_class->accuracy.value));
+	}
+
 	BUF_APPEND(", %soffset-s=%" PRId64 ", "
 		"%soffset-cycles=%" PRIu64 ", "
 		"%sorigin-namespace=%s, "
diff --git a/src/lib/trace-ir/clock-class.c b/src/lib/trace-ir/clock-class.c
index 7afc59b9..5f00e5e4 100644
--- a/src/lib/trace-ir/clock-class.c
+++ b/src/lib/trace-ir/clock-class.c
@@ -327,6 +327,36 @@ void bt_clock_class_set_precision(struct bt_clock_class *clock_class,
 	BT_LIB_LOGD("Set clock class's precision: %!+K", clock_class);
 }
 
+BT_EXPORT
+void bt_clock_class_set_accuracy(bt_clock_class *clock_class,
+		uint64_t accuracy)
+{
+	BT_ASSERT_PRE_NO_ERROR();
+	BT_ASSERT_PRE_CLK_CLS_NON_NULL(clock_class);
+	BT_ASSERT_PRE_DEV_CLOCK_CLASS_HOT(clock_class);
+	BT_ASSERT_PRE_CC_MIP_VERSION_GE(clock_class, 1);
+	BT_ASSERT_PRE("valid-accuracy", accuracy != UINT64_C(-1),
+		"Invalid accuracy: %![cc-]+K, new-accuracy=%" PRIu64,
+		clock_class, accuracy);
+	clock_class->accuracy.value = accuracy;
+	clock_class->accuracy.base.avail = BT_PROPERTY_AVAILABILITY_AVAILABLE;
+	BT_LIB_LOGD("Set clock class's accuracy: %!+K", clock_class);
+}
+
+BT_EXPORT
+bt_property_availability bt_clock_class_get_accuracy(
+		const struct bt_clock_class *clock_class, uint64_t *accuracy)
+{
+	BT_ASSERT_PRE_NO_ERROR();
+	BT_ASSERT_PRE_DEV_CLK_CLS_NON_NULL(clock_class);
+	BT_ASSERT_PRE_CC_MIP_VERSION_GE(clock_class, 1);
+	BT_ASSERT_PRE_DEV_NON_NULL("accuracy-output", accuracy,
+		"Accuracy (output)");
+
+	*accuracy = clock_class->accuracy.value;
+	return clock_class->accuracy.base.avail;
+}
+
 BT_EXPORT
 void bt_clock_class_get_offset(const struct bt_clock_class *clock_class,
 		int64_t *seconds, uint64_t *cycles)
diff --git a/src/lib/trace-ir/clock-class.h b/src/lib/trace-ir/clock-class.h
index c1d71e30..c1cca320 100644
--- a/src/lib/trace-ir/clock-class.h
+++ b/src/lib/trace-ir/clock-class.h
@@ -38,6 +38,7 @@ struct bt_clock_class {
 
 	uint64_t frequency;
 	struct bt_property_uint precision;
+	struct bt_property_uint accuracy;
 	int64_t offset_seconds;
 	uint64_t offset_cycles;