2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_UTIL_H
8 #define BABELTRACE2_UTIL_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
23 @defgroup api-util General purpose utilities
26 General purpose utilities.
28 This module contains general purpose utilities.
35 Status codes for bt_util_clock_cycles_to_ns_from_origin().
37 typedef enum bt_util_clock_cycles_to_ns_from_origin_status
{
42 BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
= __BT_FUNC_STATUS_OK
,
46 Integer overflow while computing the result.
48 BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
= __BT_FUNC_STATUS_OVERFLOW_ERROR
,
49 } bt_util_clock_cycles_to_ns_from_origin_status
;
53 Converts the clock value \bt_p{cycles} from cycles to nanoseconds
54 from the clock's origin and sets \bt_p{*ns_from_origin} to the
57 This function considers the clock's frequency in Hz (\bt_p{frequency}),
58 an offset from its origin in seconds (\bt_p{offset_seconds}) which
59 can be negative, and an additional offset in cycles
60 (\bt_p{offset_cycles}).
64 -# Converts the \bt_p{offset_cycles} value to seconds using
66 -# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}.
67 -# Adds the values of 1., 2., and \bt_p{offset_seconds}.
68 -# Converts the value of 3. to nanoseconds and sets
69 \bt_p{*ns_from_origin} to this result.
71 The following illustration shows the possible scenarios:
73 @image html clock-terminology.png
75 \bt_p{offset_seconds} can be negative. For example, considering:
77 - A 1000 Hz clock.
78 - \bt_p{offset_seconds} set to −10 seconds.
79 - \bt_p{offset_cycles} set to 500 cycles
80 (that is, 0.5 seconds).
81 - \bt_p{cycles} set to 2000 cycles (that is, 2 seconds).
83 The computed value is −7.5 seconds, so this function sets
84 \bt_p{*ns_from_origin} to −7,500,000,000.
86 This function can fail and return the
87 #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
88 code if any step of the computation process causes an integer overflow.
91 Clock's value (cycles).
93 Clock's frequency (Hz, or cycles/second).
94 @param[in] offset_seconds
95 Offset, in seconds, from the clock's origin to add to
96 \bt_p{cycles} (once converted to seconds).
97 @param[in] offset_cycles
98 Offset, in cycles, to add to \bt_p{cycles}.
99 @param[out] ns_from_origin
100 <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{cycles}
101 converted to nanoseconds from origin considering the clock's
104 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
106 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
107 Integer overflow while computing the result.
110 \bt_p{frequency} is not 0.
112 \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
114 \bt_p{frequency} is greater than \bt_p{offset_cycles}.
116 \bt_p{offset_cycles} is less than \bt_p{frequency}.
117 @bt_pre_not_null{ns_from_origin}
119 @sa bt_clock_class_cycles_to_ns_from_origin() —
120 Converts a stream clock value from cycles to nanoseconds from the
121 origin of a given clock class.
123 bt_util_clock_cycles_to_ns_from_origin_status
124 bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles
,
125 uint64_t frequency
, int64_t offset_seconds
,
126 uint64_t offset_cycles
, int64_t *ns_from_origin
);
134 #endif /* BABELTRACE2_UTIL_H */