Commit | Line | Data |
---|---|---|
0f2d58c9 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
0f2d58c9 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
0f2d58c9 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_UTIL_H |
8 | #define BABELTRACE2_UTIL_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
4fa90f32 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
0f2d58c9 PP |
16 | #include <stdint.h> |
17 | ||
18 | #ifdef __cplusplus | |
19 | extern "C" { | |
20 | #endif | |
21 | ||
43c59509 PP |
22 | /*! |
23 | @defgroup api-util General purpose utilities | |
24 | ||
25 | @brief | |
26 | General purpose utilities. | |
27 | ||
0e0c04cf | 28 | This API offers general purpose utilities. |
43c59509 PP |
29 | */ |
30 | ||
31 | /*! @{ */ | |
32 | ||
33 | /*! | |
34 | @brief | |
35 | Status codes for bt_util_clock_cycles_to_ns_from_origin(). | |
36 | */ | |
c4c4586d | 37 | typedef enum bt_util_clock_cycles_to_ns_from_origin_status { |
43c59509 PP |
38 | /*! |
39 | @brief | |
40 | Success. | |
41 | */ | |
c4c4586d | 42 | BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
43 | |
44 | /*! | |
45 | @brief | |
46 | Integer overflow while computing the result. | |
47 | */ | |
c4c4586d PP |
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; | |
0f2d58c9 | 50 | |
43c59509 PP |
51 | /*! |
52 | @brief | |
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 | |
55 | result. | |
56 | ||
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}). | |
61 | ||
62 | This function: | |
63 | ||
64 | -# Converts the \bt_p{offset_cycles} value to seconds using | |
65 | \bt_p{frequency}. | |
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. | |
70 | ||
71 | The following illustration shows the possible scenarios: | |
72 | ||
73 | @image html clock-terminology.png | |
74 | ||
75 | \bt_p{offset_seconds} can be negative. For example, considering: | |
76 | ||
77 | - A 1000 Hz clock. | |
1eca514c | 78 | - \bt_p{offset_seconds} set to −10 seconds. |
43c59509 PP |
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). | |
82 | ||
1eca514c PP |
83 | The computed value is −7.5 seconds, so this function sets |
84 | \bt_p{*ns_from_origin} to −7,500,000,000. | |
43c59509 PP |
85 | |
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. | |
89 | ||
90 | @param[in] cycles | |
91 | Clock's value (cycles). | |
92 | @param[in] frequency | |
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 | |
102 | properties. | |
103 | ||
104 | @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK | |
105 | Success. | |
106 | @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR | |
107 | Integer overflow while computing the result. | |
108 | ||
109 | @pre | |
110 | \bt_p{frequency} is not 0. | |
111 | @pre | |
112 | \bt_p{frequency} is not <code>UINT64_C(-1)</code>. | |
113 | @pre | |
114 | \bt_p{frequency} is greater than \bt_p{offset_cycles}. | |
115 | @pre | |
116 | \bt_p{offset_cycles} is less than \bt_p{frequency}. | |
117 | @bt_pre_not_null{ns_from_origin} | |
118 | ||
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. | |
122 | */ | |
c4c4586d PP |
123 | bt_util_clock_cycles_to_ns_from_origin_status |
124 | bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles, | |
0f2d58c9 | 125 | uint64_t frequency, int64_t offset_seconds, |
4c81a2b7 | 126 | uint64_t offset_cycles, int64_t *ns_from_origin) __BT_NOEXCEPT; |
43c59509 PP |
127 | |
128 | /*! @} */ | |
0f2d58c9 | 129 | |
25f74116 PP |
130 | #ifdef __cplusplus |
131 | } | |
132 | #endif | |
133 | ||
924dc299 | 134 | #endif /* BABELTRACE2_UTIL_H */ |