X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=include%2Fbabeltrace2%2Futil.h;h=6a76372dafdaa1d2fed3e9598d1f45951e7eb572;hb=33314f168f0d377bd54d42afb6614ae1d046e695;hp=8d9585c3288b07a03c6aee6187eb3d518e28240f;hpb=520cdc8260ea033f1c9f54b87d93fcb034ae8472;p=babeltrace.git
diff --git a/include/babeltrace2/util.h b/include/babeltrace2/util.h
index 8d9585c3..6a76372d 100644
--- a/include/babeltrace2/util.h
+++ b/include/babeltrace2/util.h
@@ -33,14 +33,113 @@
extern "C" {
#endif
-typedef enum bt_util_status {
- BT_UTIL_STATUS_OK = 0,
- BT_UTIL_STATUS_OVERFLOW_ERROR = -75,
-} bt_util_status;
+/*!
+@defgroup api-util General purpose utilities
-bt_util_status bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles,
+@brief
+ General purpose utilities.
+
+This module contains general purpose utilities.
+*/
+
+/*! @{ */
+
+/*!
+@brief
+ Status codes for bt_util_clock_cycles_to_ns_from_origin().
+*/
+typedef enum bt_util_clock_cycles_to_ns_from_origin_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Integer overflow while computing the result.
+ */
+ BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR = __BT_FUNC_STATUS_OVERFLOW_ERROR,
+} bt_util_clock_cycles_to_ns_from_origin_status;
+
+/*!
+@brief
+ Converts the clock value \bt_p{cycles} from cycles to nanoseconds
+ from the clock's origin and sets \bt_p{*ns_from_origin} to the
+ result.
+
+This function considers the clock's frequency in Hz (\bt_p{frequency}),
+an offset from its origin in seconds (\bt_p{offset_seconds}) which
+can be negative, and an additional offset in cycles
+(\bt_p{offset_cycles}).
+
+This function:
+
+-# Converts the \bt_p{offset_cycles} value to seconds using
+ \bt_p{frequency}.
+-# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}.
+-# Adds the values of 1., 2., and \bt_p{offset_seconds}.
+-# Converts the value of 3. to nanoseconds and sets
+ \bt_p{*ns_from_origin} to this result.
+
+The following illustration shows the possible scenarios:
+
+@image html clock-terminology.png
+
+\bt_p{offset_seconds} can be negative. For example, considering:
+
+- A 1000 Hz clock.
+- \bt_p{offset_seconds} set to -10 seconds.
+- \bt_p{offset_cycles} set to 500 cycles
+ (that is, 0.5 seconds).
+- \bt_p{cycles} set to 2000 cycles (that is, 2 seconds).
+
+The computed value is -7.5 seconds, so this function sets
+\bt_p{*ns_from_origin} to -7,500,000,000.
+
+This function can fail and return the
+#BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
+code if any step of the computation process causes an integer overflow.
+
+@param[in] cycles
+ Clock's value (cycles).
+@param[in] frequency
+ Clock's frequency (Hz, or cycles/second).
+@param[in] offset_seconds
+ Offset, in seconds, from the clock's origin to add to
+ \bt_p{cycles} (once converted to seconds).
+@param[in] offset_cycles
+ Offset, in cycles, to add to \bt_p{cycles}.
+@param[out] ns_from_origin
+ On success, \bt_p{*ns_from_origin} is \bt_p{cycles}
+ converted to nanoseconds from origin considering the clock's
+ properties.
+
+@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
+ Success.
+@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
+ Integer overflow while computing the result.
+
+@pre
+ \bt_p{frequency} is not 0.
+@pre
+ \bt_p{frequency} is not UINT64_C(-1)
.
+@pre
+ \bt_p{frequency} is greater than \bt_p{offset_cycles}.
+@pre
+ \bt_p{offset_cycles} is less than \bt_p{frequency}.
+@bt_pre_not_null{ns_from_origin}
+
+@sa bt_clock_class_cycles_to_ns_from_origin() —
+ Converts a stream clock value from cycles to nanoseconds from the
+ origin of a given clock class.
+*/
+bt_util_clock_cycles_to_ns_from_origin_status
+bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles,
uint64_t frequency, int64_t offset_seconds,
- uint64_t offset_cycles, int64_t *ns);
+ uint64_t offset_cycles, int64_t *ns_from_origin);
+
+/*! @} */
#ifdef __cplusplus
}