Commit | Line | Data |
---|---|---|
924dc299 PP |
1 | #ifndef BABELTRACE2_UTIL_H |
2 | #define BABELTRACE2_UTIL_H | |
0f2d58c9 PP |
3 | |
4 | /* | |
bbb7b5f0 | 5 | * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation |
0f2d58c9 PP |
6 | * |
7 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
8 | * of this software and associated documentation files (the "Software"), to deal | |
9 | * in the Software without restriction, including without limitation the rights | |
10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
11 | * copies of the Software, and to permit persons to whom the Software is | |
12 | * furnished to do so, subject to the following conditions: | |
13 | * | |
14 | * The above copyright notice and this permission notice shall be included in | |
15 | * all copies or substantial portions of the Software. | |
16 | * | |
17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
23 | * SOFTWARE. | |
24 | */ | |
25 | ||
4fa90f32 PP |
26 | #ifndef __BT_IN_BABELTRACE_H |
27 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
28 | #endif | |
29 | ||
0f2d58c9 PP |
30 | #include <stdint.h> |
31 | ||
32 | #ifdef __cplusplus | |
33 | extern "C" { | |
34 | #endif | |
35 | ||
43c59509 PP |
36 | /*! |
37 | @defgroup api-util General purpose utilities | |
38 | ||
39 | @brief | |
40 | General purpose utilities. | |
41 | ||
42 | This module contains general purpose utilities. | |
43 | */ | |
44 | ||
45 | /*! @{ */ | |
46 | ||
47 | /*! | |
48 | @brief | |
49 | Status codes for bt_util_clock_cycles_to_ns_from_origin(). | |
50 | */ | |
c4c4586d | 51 | typedef enum bt_util_clock_cycles_to_ns_from_origin_status { |
43c59509 PP |
52 | /*! |
53 | @brief | |
54 | Success. | |
55 | */ | |
c4c4586d | 56 | BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
57 | |
58 | /*! | |
59 | @brief | |
60 | Integer overflow while computing the result. | |
61 | */ | |
c4c4586d PP |
62 | BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR = __BT_FUNC_STATUS_OVERFLOW_ERROR, |
63 | } bt_util_clock_cycles_to_ns_from_origin_status; | |
0f2d58c9 | 64 | |
43c59509 PP |
65 | /*! |
66 | @brief | |
67 | Converts the clock value \bt_p{cycles} from cycles to nanoseconds | |
68 | from the clock's origin and sets \bt_p{*ns_from_origin} to the | |
69 | result. | |
70 | ||
71 | This function considers the clock's frequency in Hz (\bt_p{frequency}), | |
72 | an offset from its origin in seconds (\bt_p{offset_seconds}) which | |
73 | can be negative, and an additional offset in cycles | |
74 | (\bt_p{offset_cycles}). | |
75 | ||
76 | This function: | |
77 | ||
78 | -# Converts the \bt_p{offset_cycles} value to seconds using | |
79 | \bt_p{frequency}. | |
80 | -# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}. | |
81 | -# Adds the values of 1., 2., and \bt_p{offset_seconds}. | |
82 | -# Converts the value of 3. to nanoseconds and sets | |
83 | \bt_p{*ns_from_origin} to this result. | |
84 | ||
85 | The following illustration shows the possible scenarios: | |
86 | ||
87 | @image html clock-terminology.png | |
88 | ||
89 | \bt_p{offset_seconds} can be negative. For example, considering: | |
90 | ||
91 | - A 1000 Hz clock. | |
92 | - \bt_p{offset_seconds} set to -10 seconds. | |
93 | - \bt_p{offset_cycles} set to 500 cycles | |
94 | (that is, 0.5 seconds). | |
95 | - \bt_p{cycles} set to 2000 cycles (that is, 2 seconds). | |
96 | ||
97 | The computed value is -7.5 seconds, so this function sets | |
98 | \bt_p{*ns_from_origin} to -7,500,000,000. | |
99 | ||
100 | This function can fail and return the | |
101 | #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status | |
102 | code if any step of the computation process causes an integer overflow. | |
103 | ||
104 | @param[in] cycles | |
105 | Clock's value (cycles). | |
106 | @param[in] frequency | |
107 | Clock's frequency (Hz, or cycles/second). | |
108 | @param[in] offset_seconds | |
109 | Offset, in seconds, from the clock's origin to add to | |
110 | \bt_p{cycles} (once converted to seconds). | |
111 | @param[in] offset_cycles | |
112 | Offset, in cycles, to add to \bt_p{cycles}. | |
113 | @param[out] ns_from_origin | |
114 | <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{cycles} | |
115 | converted to nanoseconds from origin considering the clock's | |
116 | properties. | |
117 | ||
118 | @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK | |
119 | Success. | |
120 | @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR | |
121 | Integer overflow while computing the result. | |
122 | ||
123 | @pre | |
124 | \bt_p{frequency} is not 0. | |
125 | @pre | |
126 | \bt_p{frequency} is not <code>UINT64_C(-1)</code>. | |
127 | @pre | |
128 | \bt_p{frequency} is greater than \bt_p{offset_cycles}. | |
129 | @pre | |
130 | \bt_p{offset_cycles} is less than \bt_p{frequency}. | |
131 | @bt_pre_not_null{ns_from_origin} | |
132 | ||
133 | @sa bt_clock_class_cycles_to_ns_from_origin() — | |
134 | Converts a stream clock value from cycles to nanoseconds from the | |
135 | origin of a given clock class. | |
136 | */ | |
c4c4586d PP |
137 | bt_util_clock_cycles_to_ns_from_origin_status |
138 | bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles, | |
0f2d58c9 | 139 | uint64_t frequency, int64_t offset_seconds, |
43c59509 PP |
140 | uint64_t offset_cycles, int64_t *ns_from_origin); |
141 | ||
142 | /*! @} */ | |
0f2d58c9 | 143 | |
25f74116 PP |
144 | #ifdef __cplusplus |
145 | } | |
146 | #endif | |
147 | ||
924dc299 | 148 | #endif /* BABELTRACE2_UTIL_H */ |